This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Kolibri
- Technical writer:
- StephDix
- Project name:
- Kolibri Ecosystem Documentation Style and Workflows conventions
- Project length:
- Long running (5 months)
Project description
Abstract
This document details the implementation of Style guidelines and workflow management to Learning Equality’s documented information for the Kolibri Ecosystem project.
Overview
My proposal consists of four phases. In the first phase, I will complete the LE Documentation Style Guide with accessibility guidelines, writing, and format recommendations following LE concepts and style guidelines in software development. In the second phase, I will perform a Quality Audit over ReadTheDocs and GoogleDocs documents. The Audit plan integrates the use of checklists to evaluate compliance with Style guidelines. These checklists will help to record findings and apply changes to documentation. In the third phase, I will work on the structure, look, and feel of templates from ReadTheDocs and GoogleDocs documents. I will create a template and images repository in Google Drive identifying each template category of main document types for reuse in upcoming implementations. I will complement this task creating templates to submit document issues for easy identification in pull request reviews. Finally, I will create a Contributors Guide that will group useful resources for each group of collaborators to enhance their experience accessing information.
Purpose and scope
The intention behind this implementation plan is to improve the experience of end-users using Kolibri's documents and help team members and contributors to produce better documentation and active collaboration in the community. This implementation applies to ReadTheDocs and sub-sets of Google Docs' documents in the Kolibri Ecosystem.
Audience
A Primary audience of implementers, administrators, and end-users being the most critical consumers of the Kolibri documentation. A Secondary audience of team members and collaborators for their production and use of Kolibri documentation.
Objectives
Style Guide and workflow system for Kolibri Ecosystem Documentation expects users to: Build digestible documentation with accessible language and consistent layout. Preserve the maintenance of quality practices upon documentation. Maintain ease of access to information between documentation channels. Reinforce the collaborative initiatives in the Kolibri open-source community.
Sources of information
My sources of information were Kolibri, Kolibri Studio, Kolibri Development RTD documents, and Kolibri Toolkits from Google Drive.
The wonderful Radina Matic was a big help in providing warm-up activities and project-specific activities. Her input of what the organization conceptualizes as ""Guidelines"" and ""Guides"" and concerning the existence of a Guide for contributors helped me to organize my ideas and draft conclusions.
Software
I will develop the Style Guide draft in Google Docs. This document platform is perfect to iterate while it is ready for publication. For the QA Audit, I will use Google Forms to conduct and evaluate documents. A spreadsheet will store form responses for document control. I will refactor RTD documents using GitHub. I have worked with Git, Gitkraken, GitHub, and Gitlab. I have working knowledge of Markdown and a few RestructuredText. I'm planning to contribute to documentation fixes to continue learning the syntax. I will use Sharex for images and gifs. I love this tool because it renders in different output formats. I will use Diagrams for diagramming and images edition. Diagrams software integrates beautifully with GoogleDocs, Google Drive, and LibreOffice. State of documentation In the exploration phase, I revised most of Kolibri's documentation. I found grammatical errors, typos, inconsistencies in layout, typography, image usage, and also, confusing documentation paths from most of the project's documentation. For example, In Kolibri's User Guide, the troubleshooting section is a subtopic and not a topic. This information happens to be critical enough for end-users to have access to it from the table of contents. As a second alternative, they can use the search bar and table of contents tree to expand other topics and locate troubleshooting articles.
To access the “Troubleshooting” section you have to either search for it or expand “Manage Kolibri” to realize that Troubleshooting exists as part of the documentation. Guide vs Guidelines For this project proposal, I analyzed two documents: LE Kolibri User Documentation Style Guide and LE translation Guidelines. In the LE Kolibri Guide, I made recommendations and comments from my proposed topic outline and Documentation plan plus other few things that need improvement on the Guide. For the LE Translation Guidelines, I changed the format and style based on my recommendations and existing conventions on the Style Guide. What most came to my attention during the analysis was the misconception that exists between documents categorized as Guide and Guidelines.
Outcomes
I did a quality check to the LE Translation Guide in addition to suggestions and comments with a preliminary form that I explain in more detail in the QA Audit task. These are some final comments obtained from the evaluation: Broken links for ICU Syntax .js website The format used to create these Guidelines is incorrect. The document is a Guide, not Guidelines. Inconsistent typography. Incorrect use of headings and titles, Improper use of language and misuse of contractions. Improper use of Alternative texts. Over repeated statements/ instructions.
The findings for both documents are part of the Deliverables for this proposal.
Project-specific tasks
- LE User Documentation Style Guide recommendations (comments)
- LE Translation Guidelines with new styles and format.
- Topic Outline
- Project timeline
- Documentation tasks