User Tools

Site Tools


wiki:best_practices

Best practices for OpenAg Wiki

Creating documentation

When documenting an openag project:

  • Create a page in the global namespace. Name it after the project. For example, openag_brain has an openag_brain page.
  • Create any sub-pages for that project under that project's namespace. For example install instructions for openag_brain go under openag_brain/install

The wiki link syntax for creating sub-pages looks like this:

[[:openag_brain:install]]
  • If documentation changes significantly from version-to-version, create versioned docs as sub-pages under the project. So a version landing page would be created at openag_brain/0.0.1`` and versioned install instructions might be placed at openag_brain/0.0.1/install''.
  • Link to and indicate the most recent version from the project landing page (openag_brain). Also provide a list of all previous version pages from the project landing page.

Here's an example of a well-formed layout for openag components:

  • openag
    • Foundation stuff
  • food_computer
    • 2.1.0-alpha.1
      • bom
      • build
      • upgrade
    • 2.0.0-alpha.1
      • bom
      • build
      • upgrade
    • 2.x
      • architecture
    • 1.0.0-alpha.1
      • bom
      • build
  • openag_brain
    • 0.0.x
    • 0.0.y
    • 0.0.z
    • api
      • 0.0.1
      • cookbook
    • cli
    • install
    • docker
    • database
      • fixtures
    • ros
  • openag_python
    • 0.0.x
    • cli
    • install
wiki/best_practices.txt · Last modified: 2017/01/10 18:21 by gordonb