Note: This document is a draft, not yet adopted by the community.

Please provide comments here: Comments

Rules:

• All design documents are to be announced on the community forum: http://community.pbspro.org/
• The announcement should contain a link to the design document and a brief description
• All designs are to be posted on https://pbspro.atlassian.net/wiki/spaces/PD
• Initial drafts need only contain a title and overview with technical details to follow
• Comments are to be posted to the community forum in response to the announcement
• Code changes must be consistent with the design document prior to merge

General Guidelines:

• Prior to becoming open source, PBS Pro design documents were classified as internal (IDD) or external (EDD). This distinction no longer exists now that PBS Pro is a community project. Henceforth, design documents will no longer carry the terms "internal" or "external".
• Consider your audience when you write design documents. PBS Pro developers, test developers, testers, publications staff, system administrators, and users have different needs. Try to anticipate the questions they want answered.
• Be concise in your descriptions.
• Use illustrations when appropriate.
• Provide examples when appropriate.
• Do your best to anticipate questions your audience will have, and answer them concisely
• Keep your document updated as you develop your code
• Examples of design documents that are consistent with these guidelines may be found here: TBD

Design Document Guidelines:

Design documents are to contain the following mandatory components:

• 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 end user documentation
    • Include large amounts of code
    • Cover details best left as comments in the code

OSS Site Map

Project Documentation Main Page

Developer Guide Pages