Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Your documentation tree needs to be written to be skimmed, because the search functions are never good enough to let people find the bits they’re looking for. Either they are new and know nothing, or they’re looking for some old info they can’t quite recall. They aren’t there to read for pleasure, so don’t presume that the existence of documentation is sufficient for people to be satisfied.

It’s not enough to write the docs, you have to organize them too, in a Wiki, and keep organizing them. It only takes a few hours a month. You can do it when you’re blocked, or finish your tasks a little early on a day/week and it’s pointless to start something new because you’re leaving for the day in a half hour or the weekend in an hour and a half.

The on boarding docs and the latest initiatives go on the first page, but as new things are started the old ones need to be grouped by conceptual area and pushed down one level. When those areas get too big, push down again.

When I tried to describe my process to someone I realized I was essentially applying the B-tree algorithm to our wiki, with the slight modification that all out of date docs are footnotes on the newest. Eventually all of the dated documentation becomes leaf nodes where people don’t see them and mistake them for authoritative.



Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: