Documenting Dakota

Documentation Overview

Dakota is documented primarily through

  • Dakota User’s Guide (Sphinx documentation with source in dakota/docs/user): primarily focuses on enabling a non-expert to use Dakota. Put high-level usage guidelines here, and at least a summary of key features and how they benefit a user. The Sphinx docs also include:

    • Detailed Keyword Reference, which draws from metadata in dakota/docs/keywords

    • Dakota Theory: technical details on use or implementation

    • Developer Guide you’re currently reading

  • Dakota Examples Library: use case-driven runnable examples and tutorials; in separate peer repository dakota/dakota-examples and corresponding site-specific SNL-internal repository.

  • Dakota C++ Developer Manual: Doxygen format with front matter in dakota/docs/dev

Principles for Authoring

Favor flexibility over rigidity

  • This page consists of suggestions and guidelines, not laws. You can always deviate from this page’s suggestions if there is a good reason for it.

Favor brevity over verbosity

  • This cannot be overstated. Long pages with long paragraphs create immense cognitive load for a reader who just wants to figure out how to get something to work.

    • Live by the words of Cicero: “If I had more time, I would have written a shorter letter.”

    • Cross-references are your friend, and will make pages shorter. When possible, split topic areas into multiple Sphinx pages that are grouped together.

    • As with code, if you catch yourself copy-pasting information into multiple pages, it probably means you need to put the information in a common area and reference it.

Favor conventions over exceptions

  • If you find yourself standing on your head to import something into the new documentation system, consider whether there are any alternate approaches using existing tools/features that Sphinx or markdown (either ReStructuredText or Markdown) already provide.

Favor the best version of duplicated content

  • If information appears in two or more places, favor using the version that is either more accurate, more clearly-stated, more recent, or more complete (not necessarily longer).

  • Don’t be afraid to delete one of the versions, but review it to see if there are any interesting sentences/thoughts worth adding to the “main” page

    • Is there different phrasing or unique perspective? Is there information that is missing from the main page that we’re keeping?

    • Remember that everything is either under version control, or is still in the old manuals, so there’s no danger of permanently losing a piece of information.

Favor images and directed instructions over explanatory prose

  • Longer explanations should go into theory manual sections

Favor multiple mediums over text

  • If content appears in multiple mediums (i.e. videos and written text), duplication is ok because we’re offering multiple ways to learn something.

Favor expertise when editing

  • Take ownership of pages you are confident about editing - no need to do a formal review process for small changes or changes you can speak with authority on.

  • If in doubt about updating a page or deleting from a page, talk to the SME for that page’s topic.