OpenPBS Design Document Guidelines

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, OpenPBS design documents were classified as internal (IDD) or external (EDD). This distinction no longer exists now that OpenPBS is a community project. Henceforth, design documents will no longer carry the terms "internal" or "external".
• Consider your audience when you write design documents. OpenPBS 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:
  
  • Packaging OpenPBS for Third Party Linux Repositories

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 issue 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 OpenPBS 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

Developer Guide Pages