Item — HN Reader

1) That's what docs/training are for.

2) Writing the answer down in a wiki takes exactly the same amount of time as writing the answer in email. It doesn't need formalizing, just recording.

3) Again, the time it takes to tell someone is the same as the time it takes to write it down.

This is a solvable problem, we just have to break the perception that "documentation" is onerous and heavy-weight. That's what wikis were meant to solve.

For example - ppl are only allowed to answer questions with wiki links. My team did this, it worked very well. Everything was documented and everyone learned to check wiki first....

2 comments

No, writing the answer down takes much longer than just vocally expressing it.

1. Few people type as fast as they talk.

2. When talking, you already have all the context of the problem of discussion. This usually doesn't need to be explicitly communicated in detail, both people are currently close enough to the issue to have most of the background. In a wiki you need to establish enough context that the page is useful to someone who comes to it with no other help. There is no point in having a wiki if you still need to talk to one of the guys who wrote it to understand it.

3. With a wiki (or any other secondary doc system) you need to organize the information and make it findable. This is a non-trivial effort as the knowledge base grows.

Personally, I'm a big fan of documentation in the code paired with a wiki or other secondary system for longer or higher-level documentation. But it is definitely more work.

In a wiki you need to establish enough context that the page is useful to someone who comes to it with no other help

Bingo.

The idea that answers can just be written in a wiki ad hoc is one of those pleasant-sounding pithy conversation-stoppers, but it's strictly notional. It's certainly true for small, bounded, well-defined, trivial and/or obvious stuff, but that's not usually the stuff people pester the experts about (well, one would hope).

1. That's fine, most ppl don't need the answer now, they need it soon enough to not be blocked.

2. Any answer without context is useless, even verbally. So include the question with the answer when you write the doc.

3. Internal wikis are inherently trees, add the answer to an existing node or create a new node.

I see most of these replies are failing wiki docs for not being perfect - you just need to be good enough. It's a living document, as it's used it will mature. The important part is capturing the information somehow, somewhere.

Stop propagating tribal knowledge and document it!

I have a weird idea... What if, on condition of answering the question, you require that the receiver update the wiki? This may not work with close collaborators, but it would work with more distant ones on the threat of withdrawing further collaboration.

That's why mailing lists are great.

1. Okay, they don't address this, but that's a marginal advantage, easily outweighed by the advantages of asynchrony and distance agnosticism alone, never mind the benefits of re-use.

2. Mailing lists hit the nail on the head here, because you have the context in the discussion thread.

3. This is a big win for mailing lists with a good search function (such as that provided by Gmail). Sure, it's not as nice as having the information painstakingly organized by a subject matter expert, but as you say, the human effort required to do that organizing is not usually available, and having the information there and searchable is far better than not having it.

That's an interesting idea, and one I have considered at length before. If I ever end up managing an organisation of any nontrivial size, I do believe we will have Mailman lists for a lot of things.

> 2) Writing the answer down in a wiki takes exactly the same amount of time as writing the answer in email. It doesn't need formalizing, just recording.

Not usually true in a wiki of any size (unless you mean creating a new page without reference to what's there and shovelling the information blindly in).

"Writing the information down in a wiki" really implies doing so in a useful way. Probably: - identifying where the information should go - cleaning it up to remove redundancy (stuff already in the wiki) - correcting existing wiki content which you discover was wrong/out of date as you go to make your changes - changing to adopt the writing/layout style of the wiki - etc. etc.

Of course its common for wikis to not be maintained like this - maybe even the norm - which is perhaps why the "dump and then search later" strategy of gmail, slack etc. is pretty successful.