OpenPBS Design Document Guidelines

• 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

• 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 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