This is the multi-page printable view of this section. Click here to print.
Technical
1 - Concept document
Concept documents bridge users’ existing knowledge with the information they need to use a product. My “About Chronologue Relay P2P Protocols”—which appears on a website created with the Sphinx static site generator—models this type of documentation.
Read the document
Background
I wrote “About Chronologue Relay P2P Protocols” as a contributor to The Good Docs Project, an open-source project that offers templates and resources to advance documentation best practices.
This document:
Models how product development teams, documentarians, or other users can put The Good Docs Project’s Concept template to use.
Specifies need-to-know conceptual information for fictional users of an imaginary product, the Chronologue Relay.
- The Chronologue Relay enables its (fictional) users to experience observations from the Chronologue—an (imaginary) time-travel telescope—in 3D virtual reality.
Intended audience
This example concept document envisions a (fictional) audience of Chronologue hobbyists, museum exhibit coordinators, STEM researchers, university educators.
Example user goals
- Acquire the Chronologue telescope data needed to support VR experiences of astronomical events from across time.
- Develop and present 3D visualizations that either (a) illustrate key space and time concepts for a student or public audience or (b) demonstrate scientific research for a professional audience.
- Share events with Chronologue Relay community members.
Example technical familiarity
- Users are comfortable with digital technology, but not so advanced that they can customize their interaction with the Chronologue API or contribute to KronoPy-developed libraries for manipulating Chronologue data.
Example user pain points
- OCTAVIA’s data rate limitations restrict what they can view in VR from a direct Chronologue API data stream.
- Their incomplete understanding of Chronologue data flows leads to a suboptimal use of data resources (e.g., spending time and wasting internal database memory downloading a Chronologue event that they later realize was not interesting to them).
2 - How-to doc sequence
How-to documents lead readers through a set of steps to achieve a specific goal. The following onboarding articles, which I published in Confluence for The Good Docs Project, provide an example of this type of documentation.
Read the documents
Background
The Good Docs Project knowledge base team developed an onboarding guide to support new contributors. As a member of (and later a co-lead of) the team, I wrote this series to enable readers to:
Use GitLab for project management purposes
Collaborate effectively with the Good Docs team
In reaching these goals, contributors begin actively participating in Good Docs work to make a real, hands-on impact.
3 - User personas
User personas provide a representation of a product or service’s users. Product development teams leverage these models to center their work on authentic human needs. Technical writers, for their part, develop personas to inform and heighten documentation’s user focus, improving users’ experience with the product and fostering trust.
The following user personas, developed in a collaborative open-source project, show my attentiveness to user needs.
Read the document
Background
The Good Docs Project’s Chronologue team collaboratively developed user personas to support its documentation of the Chronologue telescope, a fictional technology created to show Good Docs software documentation templates in action. As a contributor, I drafted the bulk of the material for the (fictional) user Researcher Rahim.
This document:
Models use of The Good Docs Project’s User personas template.
Articulates user attributes and needs for The Good Docs Project’s Chronologue team to reference when creating documentation for OCTAVIA, an imaginary “multi-national government-sponsored entity that developed, built, and launched” the Chronologue time-travel telescope.