Hacker News Reader

Comment by bluGill | Hacker News Reader

I have a strict rule, anytime someone asks me a question I respond by checking the documentation for that, and writing or fixing it as needed. Once I think the documentation is correct I tell them how to find it, and ask them to tell me where something doesn't make sense so I can fix it.

As an expert I often think things are obvious that are not. So it takes a few rounds to make useful documentation.

View on HN

I call this read-through documentation (a la caching), in that you're always reading from the documentation (cache) and a missing document pulls it into the documentation (by writing it), before servicing the request.

It takes discipline, as otherwise everyone skips the "write documentation" step, and it will annoy some people with high priority issues.

But IMHO, it's the only thing that actually scales if you truly want comprehensive, continuously-updated documentation.

Side note: An excellent way to generate drafts for missing content is have your new hires write them as they get up to speed. By definition they're looking everything up, so they'll notice gaps. And they have time, before they're fully up to speed. And as long as someone with knowledge proofs their draft, their lack of experience shouldn't matter.

My strict rule : Never write/store documentation that is separate from underlying 0s & 1s. It always goes out of sync.

We are currently in the process of creating a data dictionary for our company.

I put down a rule that we are not ever going to create a SEPARATE WordDoc/Wiki/Evernote/GenZ-tool.

If it is code, document its meaning (english explanation for laymen) in the doc string. If it is data, document its meaning in the column's metadata (all database systems provide a property/comment/description capability at table & column level). If it requires complex diagrams, put these in whatever files (doc/image/pdf/mp3), store it as a blob in a database and create a link it in original code comments/column metadata.

All this data is then constantly pulled into some data-mart on top of which a query-able UI is created.

Every documentation must be literally "Tied" to actual systems making money for the company.

If a new code/data is created or updated, and it's missing documentation, PR is not approved. Once the basic technical setup of tying code/data with comments/metadata is done, enforcing this rule of updating documentation is the job of management/CTO culture.

This is a great approach.

How do you deal with outdated info that's still useful to keep around?

I have a few internal wiki-pages which are 80% 'stuff I tried that doesn't work but I'd like to keep around because the tries are valuable in case I re-visit these angles', 20% 'stuff that worked in the end'. I find the 80% confuse newcomers, and I still have to explain which parts are important.

I have a separate content category called The Stacks. If you're looking around in there, you are having a bad day, but it's come in handy a few times.

Put it in an "archive" category and auto-insert a header at the top of every page under /archive explaining that it's old and probably outdated but kept around for historical research purposes.

The more general concept behind that is called document life cycle. Ideally you would want to have different possible status, like draft, published, verified, outdated, archived. Most wiki tools don't handle that well. And make outdated = archived which is an issue as in your case, will not work, and outdated documents will keep polluting your knowledge base

I like having a section in a project document titled approaches tried and why we're not doing that. It sounds like this maybe whole projects/products that have died. Maybe large titles that say canceled, discontinued, or whatever.

On the other hand if you have good version control over the wiki, and a way to search the version history as well, kill the zombies.

Just like killing zombies in your code, killing zombies in documentation sounds good. https://www.bitnative.com/2012/10/22/kill-the-zombies-in-you...

I'm in the process of creating an internal documentation wiki + system for my organization.

You separate out them out into 2 related parts of documentation. My guess is that you want them in the same wiki page because that's how you wrote it and that's how the information lives in your head since it's all for the same project, but from an information management point of view, they're two different pieces of information with mutually exclusive metadata properties.

More broadly, ideally you talk to other people and find out where THEIR 80% 'stuff I tried that doesn't work but I'd like to keep around because the tries are valuable in case I re-visit these angles' information lives and collect it all together and presented in a way where people know going in that they're looking at historical information for the sake of current decision making.

We do the exact same thing. Whenever we answer a question, the MO is to "point to the answer in the documentation and, if it's not there, add it and then point to it".

I used this approach when doing the DevRel for Chrome DevTools. I would browse Stack Overflow for uses cases not explained in the docs, add a doc for it, and then link my Stack Overflow answer to the (newly created) official doc.

That is a great idea. We have a company-wide OneNote notebook with some (extremely) rudimentary documentation, I hope I’ll remember this the next time someone asks me a question, so I can add it there :)

Where is the documentation stored? One of my main blocks is how hard it is to update documentation.

Where is just a tool, don't get too locked into a tool just get one and use it. The important part is that IT will agree to move move your URLs around every few months.

Interesting. For me it's a problem of speed. How fast can I find it, and how fast I can edit it.

I rely on git repos using markdown because it's fast and I can search, however things like tables etc can get annoyingly complex to upkeep.

Reply on news.ycombinator.com