...
- 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
- Do:
- 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
- Do:
- 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.)
- Do:
- 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?
- E.g. is a new attribute being added?
- 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
- Do:
...