OpenPBS Design Document Guidelines

Owned by Michael Karo
Last updated: Dec 22, 2020 by Anne Urban
2 min read

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:

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