Documentation Strategy

From Open Source Ecology
Jump to: navigation, search

Documentation Key Summary

Documentation involves the transfer of information.

The top open documentation priorities are:

  • Quality Content
  • Quick Navigation
  • Ease of Editing

Documentation Platform Summary

Currently, we use a combination of the Wikimedia platform and Github. Consider how an effective documentation platform would integrate webpage content and locally stored content.

We are looking for:

  • Ease to download entire project contents to a local directory (required for people to easily start their own projects based on existing project information)
  • Ease of navigating and understanding the local content (required for people to easily use project content that is downloaded to their local storage)
  • Ease of editing the local content (fits into above, but involving editing)
  • Ease of syncing with project repositories (web-hosting and updating the contents of a project is necessary for others to access the project's files and documentation)

We need to consider a stand-alone program that is executable from a locally pulled project repository. This stand-alone program should allow ease of local content navigation and understanding as well as ease of local editing. Downloading the repository to start with as well as syncing the local contents would then be considered as functions of another program more focused on file downloading and uploading. Perhaps all 4 functional modules into 1 software would be better streamlined.

Final Product Release Documentation Template for Book/PDF/eBook

This is what a final product release document should contain.

Understand It

This section is a holistic story of the tool

  1. What Is It Used For?
    • Problems the machine addresses
    • How the machine improves our lives
  2. How Does It Work?
    • What are the physics behind this machine?
    • What is the rationale behind the machine’s design?
  3. History Of This Tool
    • Social History
    • Inventor Crediting

Build It

Step by step breakdown of how to manufacture this tool.

  1. Overview of entire process
    This is useful for a remote FabLab to know what exactly to invest in before entering the enterprise.
    • All tools needed
      • Sourcing
    • All materials needed
      • Sourcing
    • All proficiencies needed
      • Links to Wikipedia or other information source
  2. Chronological Process Breakdown
    Standard format operations manual similar to those included with consumer and professional devices. Includes images and videos for each operation
    • Tools Needed
    • Materials Needed
    • Step-by-step manufacture instructions
GREEN TEXT: Documenter decides whether this is necessary depending on specific process

Possible keywords for process breakdown

  • Making Components (Fabrication?)
  • Assembling Components (Assembly?)
  • Painting & Finishing
  • Material
  • Electronic
  • Hydraulic
  • Biological
  • Neurological
  • Quantum
  • Software

Use It

Standard format operations manual similar to those included with consumer and professional devices. Includes images and videos for each operation

  1. Operations Manuals
    • Operations Manuals Keywords
      1. Advanced User
      2. Basic User

Troubleshoot It

Known issues and community base for troubleshooting and repairs.

  1. Known Symptoms and their causes in a wiki (any logged-in user can edit)
  2. Community Discussion Page (Forum style)
    • Topics -> Threads -> Discussions
    • Community Q/A Page
    • A Question -> Multiple answer format with best answer voting system

Documentation Process