This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- TheGoodDocsProject
- Technical writer:
- Loquacity
- Project name:
- Information architecture guide
- Project length:
- Standard length (3 months)
Project description
Information Architecture Guide Plan
This document covers planning for an information architecture guide for the Good Docs Project. It was prepared as part of a Google Season of Docs 2020 submission. It outlines the use case for the proposed guide, and sketches out a plan of the structure of such a guide, for planning purposes.
Information architecture (IA) concerns how content is organised. It covers the structure of content without defining the style or words used within the content itself. For example, an IA plan would consider who the reader is, how they approach the content, and the environment within which they are reading. It would then consider an appropriate structure for the content that would best serve these reader requirements.
In a perfect world, documentation is designed by starting with a content strategy, which uses business goals to define the goals of the documentation. The content strategy is then used to create an IA, which defines the layout and structure of the documentation. From there, toolchains can be chosen, and content written. The reality of most open source projects is that the content strategy is as simple as "write some documentation so people know how to use this project", but even that simple strategy is enough to be able to define an effective IA.
The intent of this guide is to provide a simplified tool for non-professional writers to develop an IA that is sufficient for determining which templates they should use. It should be simple enough to be completed by an ordinary human in an afternoon, and should favour action over education. Ideally, it will introduce concepts in a succinct way, guide the reader to consider those concepts in relation to their own project, and use the result of that to move on to the next concept.
As scaffolding for this project, some updates to the project README are required, so that readers understand how to get started with the Good Docs Project, and are able to use the IA guide effectively to guide their template choices.
Primary audience
All people looking to use The Good Docs Project templates to create documentation for their project
Use cases: This section is designed to explore how readers approach the IA Guide. This can help us to identify how the guide should be structured in order to best serve those readers.
Scenario:
A person is working on an open source project that has little or no documentation, or a documentation suite that is badly organised or written. They decide to use The Good Docs Project to organise their documentation, but are not sure where to begin. They follow the README to understand how to get started with the templates, and follow the Information Architecture Guide to develop their content strategy and plan out how their documentation suite will look.
Proposal
Update the README to more clearly guide the new reader through the project, including clear first steps. One of those first steps would be to read and answer the questions in a new IA Guide. That guide would invite the reader to consider audience, content schema, user/task matrices, etc, without putting too much burden on the reader to learn/understand what those things are in an academic sense. Once this task is completed, the reader has an understanding of what templates are required, and how to best complete them.
Research
In order to back this up with research, I would lean pretty heavily on Abby Covert's book (http://www.howtomakesenseofanymess.com/), partly because I'm very familiar with it and it has formed the basis of a lot of content I have already written and will be making use of, but also because it's very easy for people new to IA to pick up and read if they have further interest. It's a bit of an IA gateway drug, in that sense.
Draft ToC
README:
-- Introduction to The Good Docs Project |_ Who should use the templates |_ How the templates work |_ Contributing to the project -- The templates |_ List of all current templates |_ Choosing which templates to use |_ Before you begin -- Before you start writing |_ Who reads the docs? |_ Why do they read the docs? |_ Writing for your readers
IA Guide:
-- Introduction |_ What is IA? |_ Why should I care? -- Identify the mess -- State your intent -- Face reality -- Choose a direction -- Measure the distance -- Play with structure -- Prepare to adjust