Page Comparison

...

• Title
  • Do:
    • Place your title at the top of the document
    • Make it unique, concise, and self-descriptive
    • Use the PP ID and title when applicable (72 characters max, try to stay below 50)
    • E.g. PP-1234: Improving fairshare performance
  • Don't:
    • Span more than one line
• Overview
  • Do:
    • Assume your audience consists of both technical and non-technical readers
    • Briefly describe the change being proposed
    • Describe the motivation for the change
    • Expand lesser known acronyms on first use, like IPMI (Intelligent Platform Management Interface)
  • Don't:
    • Go into too much detail
    • Use PBS Pro keywords excessively. Use generic terms where possible.
    • Expand commonly used acronyms like PBS, TCP, etc. (Use your judgement)
    • Include code or complex terminology
• Glossary
  • Do:
    • Define new or unfamiliar terms
    • Spell out lesser known acronyms (e.g. IPMI, SNMP, etc.)
  • Don't:
    • Include common terms (e.g. TCP, UDP, etc.)
• Technical Details
  • Do:
    • Assume your audience is mostly technical at this point
    • Go into sufficient detail to fully describe what will change with as little ambiguity as possible
      • E.g. is a new attribute being added?
        • What does it contain?
        • What type is it?
        • Who can read it?
        • Who can write it?
    • Use illustrations, tables, examples, and other visual aids
    • Provide instructions on how to use new parameters, commands, interfaces, etc.
    • Use multiple subsections for complex changes
    • Take the following into consideration as you design:
      • Performance
      • Scalability
      • Resilience
      • Security
      • Maintainability
      • Testability
      • Administration
      • Usability
      • Installation, upgrades, and removal
    • Discuss interfaces
      • What interfaces are being provided, and who are the consumers
      • What interfaces are being consumed, and who provides them
      • What interfaces are being deprecated or removed
    • Identify any excluded platforms (e.g. Windows only, Linux only)
  • Don't
    • Document log messages unless required for QA and testingend user documentation
    • Include large amounts of code
    • Cover details best left as comments in the code

...