The nteract documentation improvements through this project consist of clearer and prominent navigation formatting, concise and generalized language, as well usability testing for understanding the community experiences. During the project, as a technical writer, I audited the content for organization, improved language accessibility, implemented enhanced formatting and theming, as well as distributed and collected feedback from nteract users.
With the help of the nteract team, I began learning about the tools necessary for the project. We collaborated through Slack, email, virtual meetings, and GitHub in building and improving the new documentation. Throughout the timeline I developed, we met the targets of deploying an updated build of the documentation as well as collected information from the initial community survey.
Some content related to specific groups require additional text with support from developers. The plans for the material are in the documentation to add as needed when collaboration schedules line up more effectively. The build at the moment has missing elements that are in the pipeline.
The three largest factors in improving the documentation in nteract related to confirming the content available, minimizing language barriers, and engaging with the community. We used a technical communication perspective to frame each approach throughout the project.
We audited the current content for the repo as well as the documentation site to understand nteract and plan the road map for the project. We focused on organizing SDK elements in ways logical to a developer, increasing access to affinity topics in navigation and logging where material is missing for potential areas of interest.
The former SDK topics were each individual pages. Examples and other informational prose from the README files of the APIs hadn't been included yet. Moving forward with the nteract repo, we consolidated content in an outline for a general overview of the informational architecture of the documentation.
Working with developers, we grouped SDK topics according to use cases the community uses. The 24 separate pages fit into six new groups. These groups focus on their topics' affinities to one another. In an example from this project, Binder-specific material is in the same group and Myth-specific material is in its separate group. Some topics were not included as they were not necessary elements for user-facing documentation, such as /fixtures and /connected components.
With the new groups, task-based introductions and consistent headings for the table of contents improved how a user navigates the documentation to get to the information needed. While not comprehensive yet, the new informational architecture demonstrates best use cases to serve the community.
From a technical writer's perspective, quality documentation improves accessibility while being concise and accurate. Through developmental, line, and copy editing, we worked on modifying documentation text for clarity and approachability. Reducing complex prose to standards with present tense and simple sentences helped convey SDK processes in more general terms. We also focused on removing idiomatic terms and phrases as well as limiting relative clauses for more straightforward exposition.
For improved visual organization and structure, we incorporated new documentation elements of syntax highlighting for code examples. In order to include these features, we deployed a compatible theme throughout the documentation. Added benefits include drop down menu items and next page functions throughout for increased navigability.
The Markdown formatting improvements were for displaying lists and tables, splitting examples as non-headers, as well as notes within sections. We simplified organizing lists in separating bullet lists for non-instructional items and ordered lists for items with specific enumerated processes. Sections within topics have more consistent structure in conjunction with bold text before code blocks and block formatting for separated notes.
Gathering community feedback had been a highlight of the initial stages of the project. With the development of a usability test for documentation, we hoped for additional evidence to support changes to documentation and project tasks.
The Google Form survey consisted of nine questions to illustrate the community's background experience, approach, and general feedback for documentation. While responses had been sparse and slow, providing an additional avenue for users to submit and contribute to documentation they use is a strong start.
Links