This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Open Collective
- Technical writer:
- Anna e só
- Project name:
- Improve general help documentation
- Project length:
- Standard length (3 months)
Project description
First impressions It's a common occurrence to come across documentation pages containing instructions without supporting media (videos, GIFs, images) while other sections under the same chapter have more complete entries - for instance, Edit Collective is composed of instructions only while Add Fiscal Host incorporates supporting media.
In the pages I've browsed, no media is described using the alt text attribute. The lack of image descriptions hinders a complete understanding of documentation for those who use screen readers and people on slower internet connections where any media may fail to load.
Some sections of the documentation merge FAQs and direct instructions for navigating the user interface, such as Change Fiscal Host. Since there is no table of contents in the documentation interface, a user who is aware of the consequences of a change in registration records and just wants objective instructions may perceive the documentation as verbose and too tangential.
Although the language of the technical documentation is quite consistent, the publicly available Style Guide documents too little about how documentation should be written. Since the Contributing page mentions contributions to technical documentation, both Open Collective and potential contributors would benefit from more comprehensive guidelines.
Proposal I propose a review of users help pages, rethinking their presentation and current structure.
Methodology and timeline I want to improve the Open Collective documentation by working alongside the community promoting cycles of continuous feedback of varying duration.
Community bonding period (August 1 - September 1, 2019): Getting to know the Open Collective community! Interviewing active members from prominent and starting projects, asking them question about the current state of documentation (Report #1). Taking note of all internal systems used to track queries and issues and the process to document them in the Open Collective Docs (Report #2). Evaluation of latent problems in the current version of the documentation and preparation of a plan to solve them (Report #3).
September 2-6: First feedback and adjustment cycle, taking into account all comments and suggestions made by the community during the community bonding period. Is our plan good to go? Is there anything about it that needs to change? (Report #4)
September 9-20: Development of proof of concept with the less populated chapter of the documentation. Draft of a public Style Guide (Report #5).
September 23-25: Submission of the proof of concept for evaluation (closed group).
September 26-27: Does our proof of concept need any adjustments before going live? Do we need more time? Adjust accordingly. (Report #6)
September 30 - October 9: Proof of concept goes live. Second cycle of feedback (public group).
October 10-15: Final proof of concept evaluation and adjustment cycle. (Report #7)
October 16-20: Small break from activities [1].
October 21 - November 23: Public Style Guide is final (Report #8). Application of all instructions present in the Style Guide to all user documentation pages (Report #9). Report evaluating all activities performed and further recommendations for the community (Report #10).
Project duration may be extended upon request.
[1]: Trip planned before my Season of Docs application.
Deliverables - Ten public reports on the activities performed - A public style guide both Open Collective and outside contributors can use - Revamped user documentation pages