FOSS Content Creator - Documentation Development Life Cycle for GNU Linux projects

By Marcia Wilbur, Published: 07/13/2019, Last Updated: 07/13/2019

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.

ideal documentation development lifecycle - Free and Open Source 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?
How will this audience use this document?
What is the educational level of this audience?
How experienced are they with the subject matter?

 

Secondary Audience

Example:

The audience consists of teachers for ___ grade level.   

 

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804