wiki:Winter2014/Design/Documentation
Last modified 5 years ago Last modified on 11/12/2013 01:07:07 PM

DM Documentation Plan for FY14

The DM documentation effort will focus initially on filling significant gaps in the description and use of the DM Software Stack. The emphasis will be on general users of the Stack, and on enabling new DM developers to spin-up rapidly on DM design, code, and processes. Follow-on work to flesh-out a DM Space in confluence, and for managing DM project content as it is migrated from trac/wiki is also described, but work in this area will likely be deferred to mid-2014.

The major tasks are described in the following subsections. The order of the activities reflects their logical sequence and the priority for Winter14 development. Implementors, planned start dates, and estimated effort are also listed where known.

Winter14 Activities

Establish a DM Global Space in Confluence

JIRA/Confluence is the LSST Project choice for project content, planning & tracking. It appears to support most key elements of document authoring, including:

  • adequate authoring tool with reasonably expressive renderings, support for tables, graphics, and links to external resources;
  • reasonable document navigation, good documentation;
  • support for math markup with the LaTeX Math plug-in (recently installed)
  • support for export to static formats, such as PDF, XML, and HTML
Main Tasks

Create New Documents

A variety of documents are needed to acquaint new DM staff with the system. A great deal of information is sprinkled among various trac/wiki pages, but some of it is out of date. The most critical documents (with provisional authors) are:

  1. DM Documentation Plan (Shaw; due 12 Nov)[Final Draft]
    • Itemize scope for FY14
    • Estimate task effort, delivery dates
  2. DM Software User Guide (Shaw, Juric, Lim) (6 wk; draft due 17 Jan) [IN WORK]
    • Review content on current trac/wiki on this topic, and migrate relevant portions
    • Develop outline
      • Content to include: DM Stack installation
        • overview of s/w and architecture (2 wk to implement)
        • examples of running the s/w on data (<1 wk to implement)
        • high-level tour of packages & tasks (?? to implement)
        • how to use Stack in customized pipelines (2 wk to implement)
    • Compose content
    • Team-wide review
  3. DM Developer Guide (Shaw, Juric, et al.) (4 wk; draft due 14 Feb)
    • Develop outline
      • Content to include: Processes & resources for DM developers, system integration, quality review, etc. Pointers to source documentation (APIs & whatnot)
    • Compose content
    • Re-visit the question of how DM will approach source-level documentation (this may be deferred to Summer14)
    • Team-wide review

Summer14 Activities

Create More New Documents

  1. DM Production Operator Guide (Allsman, Shaw, et al.) (2 wk; due Summer14)
    • Develop outline
    • Compose content
    • Team-wide review
  2. DM Testing/QA Guide (Allsman, et al.) (3 wk; due Summer14)
    • Develop outline
    • Compose content
    • Team-wide review

Review Extant DM documentation

A review and clean-up of DM documentation is overdue. Revisions to controlled documents (requirements, design) have been made in preparation for FDR. The next step is to prioritize the DM wiki documents for migration to Confluence. The danger, of course, is that new staff may discover and use (or act on) out-of-date material unless corresponding trac/wiki documents are retired.

Main Tasks
  1. Assess existing DM documentation to determine what is reasonably current, what needs an update, and what is obsolete, among the following resources:
    • Wiki docs, including:
      • DM Standards & Policies
      • Planning docs
      • Reference material
    • Source Code
    • End-user docs (defer updates to after 2014-June)
  2. Establish a clear distinction for Documents that are maintained by DM (and a chain of responsibility for maintenance) and those that are not
  3. Develop a priority list for actions, which may include:
    • updates and/or re-factoring,
    • migration to Confluence,
    • deletion, or
    • leave on trac/wiki to wither and die
  4. Migrate DM Project documents (or links to them) from Wiki, and establish links to configured LSST/DM documents (effort: at least a month; low priority for now)
    • (KTL) We should use shortcut links to make linking to DocuShare documents (LPM/LSE/LDM/Document/Collection) easier.

Establish a Confluence Space for Periodical DM Documentation

Periodicals are those with a low- to moderate-level of formality, that are published semi-regularly. Ownership of individual documents resides with the authors. Such documents generally have limited shelf-life, and are not expected to be updated or maintained. Examples include:

  • Meeting Minutes
  • Planning Documents
  • Technical Reports
  • Code review artifacts
  • Personal notes/blogs
Main Tasks
  1. Develop boilerplate (examples, macros, etc.) for reports/presentations; style guide, etc.
  2. Create examples of each of the above Periodical types and/or migrate existing docs from wiki
  3. Create Boilerplate for reports/presentations; style guide, etc.