Alice has just joined a new team as their sole technical writer, and she has been tasked with documenting a new product or software from scratch. She

Much Ado about Documentation Structure

submited by

Style Pass

2022-09-29 21:30:09

Alice has just joined a new team as their sole technical writer, and she has been tasked with documenting a new product or software from scratch. She stares into her computer screen, unsure of where and how to begin.

For many technical writers —like Alice —figuring out documentation structure can be a source of initial confusion and overwhelm. What should you document? How should you document it? And, where should things go? Once you figure out structure, you'll have a sense of direction; once you have direction, everything's easier to start.

Structuring docs can be a very nuanced problem, and there's no one-size-fits-all that all software documentation projects can adopt. Regardless, no matter what approach you take, at a very high level, your documentation should be categorized logically, such that it intuitively answers 'where can I find information on how to do something?' for users and 'where do I put new information?' for other technical writers and contributors.

For me, two things I do to get a jump start on structure are follow common patterns of similar documentation projects and use templates for individual pages.