When creating documentation for FOSS projects, consider using the Documentation Development Life Cycle. You may be called to work on projects with existing content or style. You may be working on completely new projects with absolutely no documentation. How do you create quality usable and useful content. One way to create quality content is to use the product. Whether you have a virtual machine or some sandbox to play in or if you sit with a developer while getting a demo, understanding how to use the application or distribution is really essential to quality docs.
Example: Install and use the application by compiling in C/C++ or running in a python virtualenv
List of items also useful when creating docs:
Changelog - very useful for information about upcoming release candidate changes
Release Notes - in addition to changelog (which can be used to create Release Notes) can have additional information
Code - Attending code reviews or stand ups as well as reviewing the code can be insightful when the application is a Work in Progress. Whether the code base is Java, C/C++, python or another language - understanding code or even being a developer can be a great contribution to documentation development.
Function and Business design documents - these can list a lot of the features that are being worked on
Bug Reports/Issues - This can be useful for bug driven projects
FOSS Style Guide - Your style guide or playbook to create content includes typography, image standards, as well as usage, license and trademark information. Example: directory for GNU Linux, folder for proprietary systems.
Visuals are nice at times. Here is a visual of the documentation development lifecycle for FOSS projects.
Audience Analysis
The below template is what I've been using since 2001, with some updates/revisions. GFDL
Project Name: |
Project XYZ |
Primary Audience Profile |
Examples: - Entrepreneurs - Industrial IOT Developers - Enterprise Developers |
| What is the job function of the primary audience? How will this audience use this document? What is the educational level of this audience? How experienced are the members of this audience with the subject matter? What is the work environment like? What is the interest level? What biases, preferences, or expectations, might the audience have? How much theory or “nice-to-know” information will the audience want? What other training will they receive in addition to the content? |
|
| Prototypical User | Example: The prototypical primary user is a developer in an industrial environment. |
Secondary Audience Profile |
Example: Education/Curriculum |
| What is the job function of the secondary audience? |
|
| Secondary Audience | Example: The audience consists of teachers for ___ grade level. |
"