Project Documentation Requirements

This section is excerpted from Project Documentation Requirements, to see it in its full context, go to that page.

Kinds of Documentation

These are the expected kinds of documentation and target audiences for each kind.

  • User/Operator: for people looking to use the feature w/o writing code
    • Should include an overview of the project/feature
    • Should include description of available configuration options and what they do
  • Developer: for people looking to use the feature in code w/o modifying it
    • Should include API documentation, 
  • Contributor: for people looking to extend or modify the feature's source code
    • Note: should be documented on the wiki not in reStructuredText
  • Installation: for people looking for instructions to install the feature after they have downloaded the TF release
    • Note: audience is the same as User/Operator docs
    • For most projects, this will be just a list of top-level features and options
      • We'd also like them to note if the options should be checkboxes (i.e., they can each be turned on/off independently) or a drop down (i.e., at most one can be selected)
      • What other top-level features in the release are incompatible with each feature
      • This will likely be presented as a table in the documentation and the data will likely also be consumed by automated installers/configurators/downloaders
    • For some projects, there is extra installation instructions (for external components) and/or configuration
      • In that case, there will be a (sub)section in the documentation describing this process.
  • HowTo/Tutorial: walk throughs and examples that are not general-purpose documentation
    • Generally, these should be done as a (sub)section of either user/operator or developer documentation.
    • If they are especially long or complex, they may belong on their own
  • Release Notes:
    • Release notes are required as part of each project’s release review. They must also be translated into reStructuredText for inclusion in the formal documentation.

Requirements for projects

Projects MUST do the following

  • Provide documentation including
    • Developer documentation for every feature
      • Most projects will want to logically nest the documentation for individual features under a single project-wide chapter or section
      • This can be provided as a single .rst file or multiple .rst files if the features fall into different groups
      • This should start with ~300 word overview of the project and include references to any automatically-generated API documentation as well as more general developer information (as described above).
    • User/Operator documentation for every every user-facing feature (if any)
      • Note: This should be per-feature, not per-project. Users shouldn't have to know which project a feature came from.
      • Intimately related features, can be documented as one noting the differences
    • Installation documentation
      • Most projects will simply provide a list of user-facing features and options. 
    • Release Notes (both on the wiki and reStructuredText ) as part of the release review.
  • This documentation will be contributed to the docs repo (or possibly imported from the project's own repo with tooling that is under development)
    • Projects MAY be ENCOURAGED to instead provide this from their own repository if the tooling is developed
    • Projects choosing to meet the requirement this way MUST provide a patch to docs repo to import the project's documentation
  • Projects MUST cooperate with the documentation group on edits and enhancements to documentation
    • Note that the documentation team will also be creating (or asking projects to create) small groups of 2-4 projects that will peer review each other's documentation. Patches which have seen a few cycles of peer review will be prioritized for review and merge by the documentation team.

Timeline for Deliverables from Projects

  • M2: Documentation Started
    • Identified the kinds of documentation that will be provided and for what features
      1. Release Notes are not required until release reviews at RC2
    • Created the appropriate .rst files in the docs repository (or their own repository if the tooling is available)
    • Have an outline for the expected documentation in those .rst files including the relevant (sub)sections and a sentence or two explaining what will go there
      1. Obviously, providing actual documentation in the (sub)sections is encouraged and meets this requirement
    • Milestone readout should include
      1. the list of kinds of documentation
      2. the list of corresponding .rst files and their location, e.g., repo and path
      3. the list of commits creating those .rst files
      4. the current word counts of those .rst files
  • M3: Documentation Continues
    • The readout at M3 should include the word counts of all .rst files with links to commits
    • The goal is to have draft documentation complete so that the documentation group can comment on it.
  • M4: Documentation Complete
    • All (sub)sections in all .rst files have complete, readable, usable content.
    • Ideally, there should have been some interaction with the documentation group about any suggested edits and enhancements
  • RC2: Release notes
    • Projects must provide release notes as .rst pushed to the master branch of the docs project
  • No labels