This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- ESLint
- Technical writer:
- Khawar
- Project name:
- Reorganize/Rewrite Configuration Documentation
- Project length:
- Standard length (3 months)
Project description
Abstract
The aim of this project is to restructure the configuration documentation for ESLint and to create an effective information architecture. This will make navigation easier and also improve the usability and usefulness of the documentation.
Project Summary The configuration documentation of ESLint (https://eslint.org/docs/user-guide/configuring), in the current state, provides a lot of information on a single page. Despite the presence of headings, subheadings, and appropriate paragraphing on the page, the documentation can get overwhelming. There is no way to navigate to a particular section of the page which is frustrating for a user interested in a particular section. The information, because of this lack of organization, can also get lost, failing to serve its purpose and asking the users to put in additional effort.
These issues, however, can be resolved by a series of careful steps. I propose a content audit as the first step in this reorganization. A content audit will not only help in identifying the issues in the presentation of the information but also highlight the shortcomings of the content itself (e.g. outdated or incomplete information). I then plan to create the Information Architecture (IA) to unveil the knowledge network. This will enable us to cluster the information according to various topics and to find links between various closely related topics. The insights gained through these two practices will then be used to divide the single-page documentation into multiple pages. The entire package can then be linked and cross-referenced in Markdown. As a result, there will be a better-organized version of the configuration documentation, one that is easier to navigate and understand.
Motivation Despite the fact that I have been using open-source software for quite some time, my familiarity with the term is fairly new, similar to my knowledge of Linting software. When I started learning Python (through edX), I did wonder how tiny errors can mess the whole code up. I thought it would be nice to have your codes tested, somehow, and get your errors identified, and then I came to know about the term “linting”. I haven’t aptly used linting software yet but I’m sure these will make my life a lot easier in the days to come.
With my background in Electrical Engineering and some experience in programming, I can understand the problems of coding and the requirements of programmers in a better way. Additionally, my graduate degree in Technical and Professional Communication makes me an advocate of the users, trying to make life easier for people. My skills and expertise will serve as a good combination for this project, adding value to the documentation of ESLint.
Objectives The overarching goal of this project is to ensure that the documentation on the configuration page of ESLint is easy to comprehend and does not overwhelm the users. It is important for the success of the project that navigation through the content is made easy and free from all complications. The important objectives of the project are as follows. - Conducting a comprehensive content audit - Create an Information Architecture to understand the flow of information - Improve the Information Architecture to reorganize the documentation - Identify links and references between different sections of the content - Rewrite/Edit parts of the documentation, if necessary to meet the reconfiguration requirements
- Ensure the content is flexible and reusable
Project Description Configuration of ESLint is an important feature, one that makes ESLint customizable. Users interested in configuration would most certainly be interested in one or two aspects at a given time. It is, therefore, important that a user is guided to their particular topic of interest, thus providing them with the solution in an efficient way. The present state of configuration documentation for ESLint contains a lot of useful information but it is organized in a way that can make the users feel overwhelmed, frustrated, and lost. For instance, if someone is interested in learning about the use of third party plugins in ESLint, they will have to scroll down, through the discussion on specifying parser, environments, and globals. The entire practice is tiring for users and can drive them away from the website. Similarly, if a user is somewhere in the middle of the page and wants to go to a particular section or just to look at similar topics, it will not be an easy task for them, since no such aid is provided to the users. These issues need immediate attention as the quality of any documentation, no matter how well-drafted, is dependent on its usefulness. I propose solutions to these, and other related, issues in the discussion that follows.
Content Audit The first step in the process of reorganizing the configuration documentation would be to conduct a comprehensive content audit. The audit will aim at identifying some key issues such as outdated content, duplication, missing content, etc. A content audit spreadsheet created as a result will be shared with the management and documentation teams for their feedback. This will help in coming up with a new strategy to structure and present the documentation.
Creating Information Architecture To understand the knowledge network or the flow of information in the configuration documentation, creation of information architecture (IA) can be valuable. The findings of the content audit will serve as a good foundation to understand and develop the flow of information. An improved version of the IA will then be created to organize and present the documentation in a better way. This improved IA will not only restructure the current content but also identify links and forks between various sections of the documentation, thus creating an efficient network. For example, the content on “Configuring Rules” can be followed by a link leading to “Disabling Rules with Inline Comments”. Other such links can also be identified, thus creating relationships between different sections of the documentation.
A Table of Contents Content audit and IA will provide adequate information to create a detailed table of contents with links leading to specific sections and subsections of the documentation. Creating separate files for each section and adding appropriate references to other sections can add value to the entire set of documents. A table of contents can be created for users landing on the configuration documentation, thus aiding their journey while on the website. The table of contents can include all the first and second level headings to keep it brief yet comprehensive. One such practice, for example, is that used by Prettier (https://prettier.io/docs/en/index.html) to organize the documentation.
All the documentation will be created using Markdown to keep things simple and well-organized. Special care will be taken to ensure that the documentation is reusable as it might grow and alter in the future.
Tools to Use Some important tools which can come in handy while working on the project are - Draw.io to create illustrations for IA as needed - Atom (or a similar editor) to write and edit documents in Markdown
- GitHub to ensure version control of the documentation
Milestones From the submission of the proposal to the completion of the project, the following tentative milestones will ensure that the project is completed on time, maintaining the right flow in the process.
July 10, 2020 - August 16, 2020: Proposal review and selection I will go through the documentation of ESLint and develop the skills needed to complete the project (such as Markdown writing, collaboration on GitHub). I will also contribute to the documentation via GitHub and engage with other people to get a better understanding of the documentation.
August 17, 2020 - September 13, 2020: Community bonding During the community bonding period, I will refine my proposal as per the discussions with mentors and concerned teams. I will also edit the objectives and milestones if needed. Additionally, I will make sure to shortlist the tools which will then be used to work on the project.
September 14, 2020 - September 19, 2020: Content audit To begin with the project, I will conduct a comprehensive content audit of the configuration documentation. The objective would be to highlight issues with the content and its presentation.
September 20, 2020 - September 25, 2020: Information Architecture (IA) After the content audit, I will create the IA of the configuration documentation. I will focus on presenting the knowledge network in a way that is understandable. This will then help in making improvements to the flow of information.
September 26, 2020 - September 30, 2020: Links and reference I will analyze the IA during this phase to map out links and references between various sections of the documentation. I will also create a hierarchy of all sections, thus improving the IA in the process.
October 01, 2020 - October 03, 2020: The final map With the help of insights gained through content audit and IA, I will then create a final map to be implemented in the reorganized configuration documentation. This comprehensive map will contain a table of contents, a hierarchy of topics, and a list of links and cross-references between sections of the documentation.
October 04, 2020 - October 05, 2020: Discussion At this point, that is before editing the documentation, I will present my findings and plan to the mentors and concerned teams. Their feedback will help in refining the plan and making alterations where necessary.
October 06, 2020 - October 20, 2020: Rewriting and editing In this period, I will edit and update the sections of documents where work is needed. Some sections of the configuration documentation might be rewritten or some new stuff might be added to it. The focus in this phase will be to ensure that the documentation is accurate, updated, flexible, and reusable.
October 21, 2020 - October 25, 2020: Corrections and links In this phase, I will review my own work to get rid of grammatical and structural errors and also to double-check my work for accuracy. I will also add links and references between sections, as per the IA, to ensure that the documentation is following the knowledge map devised earlier.
October 26, 2020 - October 31, 2020: Final version for submission I will link all the Markdown files, create a table of contents, and share the drafts with the mentors. This will serve as the submission of the first draft, in the form of a complete package.
November 01, 2020 - November 05, 2020: First review During these five days, I will discuss the first draft with my mentors. I will get their feedback and discuss my ideas with them to create a list of edits that need to be made.
November 06, 2020 - November 12, 2020: First edits With the help of the mentors’ feedback, I will edit the first draft of the documentation. The actual edits will be dependent on the nature of comments and feedback but the objectives of reuse, accuracy, and flexibility will serve as the locus of the editing phase.
November 13, 2020 - November 15, 2020: Second review After the completion of initial edits, I will discuss the progress with my mentors and the concerned teams, one more time. These discussions will focus on the edits made to the first version and also highlight any other issues which may have risen in the process of editing.
November 16, 2020 - November 19, 2020: Second edits I will then dedicate a four-day period to editing the document. The versions produced as a result will be discussed with the mentors to give them a final shape. The documents, at the completion of this phase, will be in the final shape, ready to be uploaded to the website and the GitHub repository.
November 20, 2020 - November 23, 2020: Uploading on the website After making all the necessary edits, the documents will be uploaded to the website. Any issues encountered in the process will be dealt with accordingly since we will still have a few days to work on the documentation.
November 24, 2020 - November 28, 2020: Project report A detailed report of the project will be created in this five-day period. The objectives, struggles, issues, and the solutions presented will form a part of the project report. The report will be shared with the mentors for the feedback.
November 29, 2020 - November 30, 2020: Final submission The project, along with all the files, and the project report will be submitted to the mentors. A review of the entire project will be conducted via a meeting/discussion with the mentors and the concerned teams.
Throughout the project, I will keep consulting the mentors to get their valuable feedback. All these milestones can be altered based on the discussions with mentors in the community bonding and proposal review periods.
About Me I have an undergraduate degree in Electrical Engineering and a graduate degree in Technical and Professional Communication from North Carolina State University. I have experience in the fields of technical and professional writing and editing, communication and content management, web and mobile usability studies, and instruction design. I have worked as a Sub-Editor for an online publication (Global Village Space) and as a Communications Intern for Duke Forge at Duke University. Along with that, I also have an interest in creative writing.