https://developers.google.com/season-of-docs/docs/work-product
- Landing page: https://thegooddocsproject.dev/ia-guide.html
- Interactive Guide: https://thegooddocsproject.dev/ia-guide/ia-cyoa.html
- Static Guide: https://thegooddocsproject.dev/ia-guide/ia-static.html
Epics:
Issues:
- https://github.com/thegooddocsproject/planning/issues/11
- https://github.com/thegooddocsproject/planning/issues/12
- https://github.com/thegooddocsproject/planning/issues/13
- https://github.com/thegooddocsproject/planning/issues/14
- https://github.com/thegooddocsproject/planning/issues/15
- https://github.com/thegooddocsproject/planning/issues/16
PRs:
- thegooddocsproject/incubator#3 - Initial draft of interactive guide
- thegooddocsproject/incubator#5 - Github action for interactive guide
- thegooddocsproject/incubator#6 - Second draft of interactive guide
- thegooddocsproject/incubator#13 - Static guide
- thegooddocsproject/thegooddocsproject.github.io#58 - Move to site repo & enable action
Still to do:
- thegooddocsproject/templates#167 - Further edits
- Move from old Jekyll site to new Hugo site, when the new site is implemented.
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 the IA 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.
During the planning phase of the project, it was determined that there are two main audience types for this documentation: those who are looking for assistance in writing documentation for their own projects, and those who want to contribute to the Good Docs Project. For ease of reference, we refered to the first type as "external" users, as their end-goal is to produce content for a project outside of the Good Docs Project. The second type is referred to as "internal" users, as they are producing content for the Good Docs Project itself. Naturally, there is significant overlap between these two groups; some people begin as external users, and become internal (as their skills improve and they want to give back to the project), and others might begin as internal users, and act as external users from time to time (as they come across projects that would benefit from the templates).
For the IA Guide, the primary audience is external users. External users are those people who have a project - either open source or otherwise - that requires documentation. These people might have some exposure to technical writing, through using or writing documentation with previous projects, but are unlikely to be trained technical writers. They are more likely to have a development or project management background. We can assume some familiarity with software and concepts such as markdown and version control. We cannot assume familiarity with open source principles, any specific markdown language or tool, or any exposure to technical writing principles such as information architecture, content strategy, or topic-based authoring.
During a user/task analysis, it was determined that users of the IA Guide want to (in order of importance):
- Determine which templates to use (critical path score: 5)
- Research whether or not to use templates (critical path score: 4)
- Conduct a reader analysis (critical path score: 3)
In order to satisfy the primary critical path of "researching whether or not to use templates", both the site and the repo need obvious "START HERE" messaging. On the site, it should be on the index page, and in the repo it should be in the README. From there, a link leads to the IA guide. The IA guide must be structured in a way that it is easy to begin. Don't overburden the reader with too much reading or thinking straight away. This could be best addressed by a series of questions, with each answer leading naturally to the next question.
In order to satisfy the critical path of "determining which templates to use", the reader must be able to complete the IA guide in a matter of hours, and complete it with a reasonable idea of the templates required for their project. This could potentially be achieved using a simple questionnaire style "pick your own path" implementation, with buttons to click. Implemented this way, as a questionnaire on a mini-site rather than as a document, it can be easily hosted on the project site and linked to from the README/index page.
A suggestion from the community led to using the Twine platform for creating an interactive mini-site. In order to provide accessible options for all readers, and to provide a simple mechanism for revising elements of the guide, a static version was also created.
The Twine platform is primarily designed for creating interactive fiction. There are multiple ways of developing Twine projects, ranging from less to more technical in nature. In order to ensure that the project remained maintainable in the future, even after the original author had moved on, I decided to use a more technical implementation that leant itself well to automation, and ensured that future editors did not need a deep understanding of the Twine platform in order to be able to edit or update the mini-site.
The content of the mini-site was written in a Twine (ia-cyoa.tw) file, using the Chapbook-1 format. Twine supports many formats, and while Chapbook-1 is less common, it provided features that weren't available in other formats, including providing the ability for readers to input text which could then be stored as a variable and used elsewhere in the site. From there, I implemented a GitHub action that used the compiler Tweego to build the Twine file into an HTML file and publish it to the correct location on the website. The Twine file format is very similar to markdown (used elsewhere in the site), so future users can easily update the Twine file, and the GitHub Action will automatically rebuild and update the mini-site when the changes are published.
Considering your original project plan, how close did you come to meeting all the goals you originally outlined?
The original project plan stated:
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.
The IA Guide was written according to the specifications in the plan, and published. The README and associated website copy was only lightly edited, because the site is undergoing a reconstruction. When the new site is live, and the IA Guide moved to its final location on the new site, the associated copy can be updated accordingly.
Some additional work was completed during the project that was not part of the original project plan:
- The IA Guide has both an interactive and static version, to better address the use cases of readers, and reduce cognitive load.
- Some associated automation was implemented around the IA Guide, to help ease the maintenance burden.
- Some other smaller tasks, such as assistance with creation of a Base template (template of template), and general editing and updates across the project.
I did a total of 76 hours on the project, averaging 6 hours work per week.
Did you solve unexpected problems?
Yes, mostly around the choice of tool for the interactive guide. Because the tool was a new technology for me, I had to understand how it worked, and because it can be non-intuitive, I then had to ensure it was maintainable for future contributors.
Did you add needed docs that weren't on the original plan?
I ended up doing two version of the guide, to try and cover a lot of use cases. The interactivity of the IA Guide was great, but we needed to ensure we had a more accessible version of the document for other use cases. The static version also provides a skimmable version of the interactive doc, which is good for people who don't have the time to go through the interactive guide, or just want to refresh their memory of the content.
Did you contribute to the code as well as the documentation?
I wrote the Github action to maintain the interactive guide, and the IA Guide itself was written in a language called Twine, designed for interactive fiction and simple adventure-style games.
Did you improve the open source organization's contribution processes?
Yes, I wrote a Contributors' Guide as part of assisting with the creation of the Base Template, which set out how contributors can fork the repo and create PRs, and set out how to the use the various repositories to contribute, which had not previously been described.
Are there any metrics to quantify your improvements, such as increased page views or page satisfaction?
Not that I'm aware of.
Yep I can see it Lana