Documentation is important.

However, many mature projects have part-time or overworked staff, or are built of a loose collection of volunteers. Whatever the case may be, there are times when documentation is old and broken, or poorly-designed and hard to use.

This document goes over some basic ideas for creating a new "better" project.

Do note that such a project is just as vulnerable as all of those old ones. Community participation is by far the most important element.

Community ∞

Find others interested in collaborating. Assemble them in one place. Form a community to help one another with encouragement and assistance. "Moral support" is important.

• Re-use existing websites and tools. Do not get complicated right now.

  ("Better" tools can be discussed and implemented at some future point)

Find documentation software ∞

Build a list of website software engines which would be important for this project.

• Have as few tools as possible.
• Make these tools as simple as possible.
• Myopic tools are ok. Don't think too hard, and don't look into the future too far.
• This engine WILL be replaced in the future. This is version one. The current goal is to "make it work".
• Talk with the community, and try to decide on website tools. It's probably simpler to have a benevolent dictator decide this for now, since it will be replaced in time.
• Do not worry about internationalization, creating a "guidebook" PDF, etc. Keep it dead simple. These things are for a "version two" project.

• Strongly consider something which is navigable with Lynx.

  • People with broken installs often have no GUI and limited tools to troubleshoot with.

Hosting ∞

Decide on hosting.

• The documentation software, and possibly the community tools, may influence this decision.

• See if you can get the mothership website to create a subdomain, like docs.example.com

Find existing projects ∞

Build a list of candidates to absorb into this project.

Others may have attempted their own projects. Even the most passionate people can fail or eventually lose interest. It's more important at the early stages to create a community documentation project and let go of as many responsibilities as possible. This isn't delegation, this is cooperation.

Initialize content ∞

Absorb the list of documentation projects. For each each project, for each of their items:

• Keep, but flag, obviously old items.

• Keep, but flag, items which duplicate better, or official, documentation.

  ("Flagged" items will be manually reviewed and deleted at some future point)

Distant goals ∞

Additional goals can only be considered once a superior documentation project has become obvious.

• Audit the mothership website (e.g. example.com), edit documentation and try to get changes included "upstream".
  - Examine and absorb specific pages.
  - Do not "rearrange them".
  - Present edited items for approval.

  (The point of this is to "lightly improve" example.com to gain the trust of it's benevolent dictator. Only with this trust can a completely "rearranged" and edited example.com be possible.)

• Contact existing projects for decommissioning.

  • Having multiple projects scattered about, with varying degrees of quality, is bad for users.

• Decide on new project tools for a "version 2" project. Possible considerations include:

  • Internationalization
  • A version of the documentation to keep offline.
    - For some, a goal would be to provide something that gets onto an installation CD.
  • Consider a version of the documentation that's printable.

Last updated 2023-03-18 at 22:28:11