4 ms·

I haven't read your documentation so I don't know, but possible explanations: 1) Your documentation might be long-winded and they want a guided tour or executi

I haven't read your documentation so I don't know, but possible explanations: 1) Your documentation might be long-winded and they want a guided tour or executive summary, or at least a 10,000 foot view from which to start 2) Maybe they don't know where to look for what they're looking for; if you've documented a bunch of functions but provided no curated guide for what code exists and where to look based on a use-case, it might never be found

hinkley 5y ago
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.

4 ms·

I haven't read your documentation so I don't know, but possible explanations: 1) Your documentation might be long-winded and they want a guided tour or executi

by brundolf 5y ago

hinkley 5y ago
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.