3 ms·

This is a good overview on how to structure a particular page, but what about the structure of overall documentation? I've actually found several good articles

This is a good overview on how to structure a particular page, but what about the structure of overall documentation? I've actually found several good articles about writing articles, but little about organizing many of them. I find that most documentation that goes into a wiki, e.g., Confluence, begins and ends life as a plan. It is then surrounded by business process clutter. And then the true gems of reports about performance analysis or other details just get buried. What would this be even called? Taxonomy? I sometimes wonder if I could convince people to call wikis, google docs, etc, a "library" and we should have a librarian go organize everything. Because it's a little sad how much knowledge just gets lost.

chrishynes 8y ago
Yep, this! Lots of articles about low level writing, not much on the high level. I've always liked the old school documentation layouts when it used to be printed -- programmers guide, function reference, etc. but sometimes it escapes me how to apply that sort of structure to other domains.
kaycebasques 8y ago
Technical writers call this "information architecture". Hierarchical organization is tough. E.g. if you're working on a docs site, and you have a multi-level nav, what's the best way to organize that nav? Same problem with organizing the directories in a company's intranet. One idea that is influential within the technical writing community is to "treat every page as page one" [1]. Because of Search, you never know how people will first access your docs. So you always structure every page to handle one topic, and only one topic, thoroughly. And then link profusely to other docs that the user might be interested in. [1] https://everypageispageone.com/the-book/ https://everypageispageone.com/the-book/
tbarn 8y ago
Author here. This is a great point! Stay tuned for part 3 or 4 in the series where I cover some of this stuff.

chrishynes 8y ago

Yep, this! Lots of articles about low level writing, not much on the high level. I've always liked the old school documentation layouts when it used to be printed -- programmers guide, function reference, etc. but sometimes it escapes me how to apply that sort of structure to other domains.

kaycebasques 8y ago

Technical writers call this "information architecture". Hierarchical organization is tough. E.g. if you're working on a docs site, and you have a multi-level nav, what's the best way to organize that nav? Same problem with organizing the directories in a company's intranet. One idea that is influential within the technical writing community is to "treat every page as page one" [1]. Because of Search, you never know how people will first access your docs. So you always structure every page to handle one topic, and only one topic, thoroughly. And then link profusely to other docs that the user might be interested in. [1] https://everypageispageone.com/the-book/ https://everypageispageone.com/the-book/

tbarn 8y ago

Author here. This is a great point! Stay tuned for part 3 or 4 in the series where I cover some of this stuff.