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

ID 标签 688539
已更新 7/13/2019
版本 Latest



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.