Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

High-documentation, low-meeting work culture

tremendous.com

Post reply on HN
Print view View original

241–250 of 524 posts

Re: High-documentation, low-meeting work culture

#241

Post by jorgesborges »

PragmaticPulp wrote: post #158
rcarr wrote: post #134

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…

> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…

In fact you lost non-technical people at Markdown.

Re: High-documentation, low-meeting work culture

#242

Post by SgtBastard »

matwood wrote: post #115
Macha wrote: post #82

Earlier quoted context omitted.

I'd take confluence over google docs because of how bad Google Docs' search is surprisingly

Interesting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.

Confluence’s search is so bad, it might as well be a Write Once, Read Never tool.

Re: High-documentation, low-meeting work culture

#243

Post by evolve2k »

rcarr wrote: post #222
remus wrote: post #207

Earlier quoted context omitted.

I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about ho…

I do agree that an online google doc style WYSIWYG markdown solution would be preferable for non technical and then git and markdown for technical would be the ideal solution.

My sense is the markdown/git/render a documentation wiki with mkdocs is mostly solved. The issue is having that easy interface for non-tech folk.

And related to this is the state of WYSIWYG markdown editing.

The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues.

Basecamp explained the issue with most approaches as such:

> Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers.

> Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies.

> Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all.

Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow.

Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?

Re: High-documentation, low-meeting work culture

#244

Post by triceratops »

beachy wrote: post #187
origin_path wrote: post #132

Earlier quoted context omitted.

It does matter because the issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy. That's the average wiki. It's a commons and a tragic one. To…

> To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc. Maybe true in large orgs. But for smaller companies what I've seen is usually paralysis. e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening.…

Ticket, or pull request?

Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.

Re: High-documentation, low-meeting work culture

#245

Post by eastbound »

goatlover wrote: post #210
rcarr wrote: post #183

Earlier quoted context omitted.

1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.

So you're replaced something that's simple as paste in office documents with two separate steps, one outside the app requiring the user to navigate to the assets folder, and the second requiring remembering specific syntax.

“Stop, you were born with computers so you don’t notice it, but I’m not technical enough to paste an image in a Word document.”

— The intern I just had to fire last month. She pretended because her generation was born with iPhones, that knowing advanced computer skills like Cmd+V was something that wasn’t a given at 21 years old. It blew my expectations about school - but at least school teaches them to find unexpected arguments.

Re: High-documentation, low-meeting work culture

#246

Post by vsareto »

jasmer wrote: post #118
hinkley wrote: post #91

Earlier quoted context omitted.

People hate reading bad writing. As someone who dabbled in creative writing before discovering my vocation, I see a lot of problems caused by people not bothering to explain themselves clearly. As my time in the industry grew I begin to see people who were confused about their own ideas and came to see how many things we don’t even explain to ourselves. Which likely plays a role in how defensive people get about some…

It's shocking how many people don't have the ability to organize their thoughts. I'm ashamed that I was completely guilty of this myself. At some degree of professional development in software, you start to verbalize things, so as to 'explain them to yourself' and it helps clear things up. This helped me understand that 'writing skills' (in this context) are frankly more matter of being able to organize concepts more…

> It's shocking how many people don't have the ability to organize their thoughts.

It's organized for them, but not for others. This skill is not intuitive to learn, so it shouldn't be shocking.

Re: High-documentation, low-meeting work culture

#247

Post by justin_oaks »

jl6 wrote: post #14

High-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system. Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet…

This reminds me of when leadership announces a policy over email. Sure, all the people who got the email can follow it, but what about people who join the team in the future? Either they find out about the policy when they violate it and get reprimanded, or they hear about it via word of mouth.

I've seen it a number of times in my career.

Re: High-documentation, low-meeting work culture

#249

Post by pmoriarty »

namdnay wrote: post #131
mr_gibbins wrote: post #128

Earlier quoted context omitted.

I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?

My experience is that for internal documentation the time spent explaining things to a technical writer is bigger than the time spent writing the documentation This isn’t the case for external documentation, that has to be more polished, needs sign offs and images and demos and stuff - tech writers can come in useful here

Most developers just don't like writing docs, are too busy to write them, and aren't very good writers anyway.

So even on those rare occasions when they do actually document something, the documentation tends to be pretty bare-bones and not very readable.

Good technical writers are worth their weight in gold.

Re: High-documentation, low-meeting work culture

#250

Post by The_Colonel »

heydonovan wrote: post #237
beachy wrote: post #187

Earlier quoted context omitted.

> To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc. Maybe true in large orgs. But for smaller companies what I've seen is usually paralysis. e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening.…

Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces. The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards…

> A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit.

A ticket represents a process (otherwise it has no added value over git commit message) and thus creates much more work than a couple of seconds.

Post reply on HN