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
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.
Sandia National Laboratories is a multimission laboratory managed and operated by National Technology and Engineering Solutions of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the U.S. Department of Energy’s National Nuclear Security Administration under contract DE-NA-0003525.
