Available at https://dmtn-030.lsst.io/v/v1.
Last month, @mssgill, @KSK, @swinbank and I met in Tucson to design the documentation system for the LSST Science Pipelines (https://pipelines.lsst.io). This documentation will cover everything from installing the pipelines and processing data, to detailed task and API references.
DMTN-030 is a report of the design decisions made in that meeting, and will serve as an evolving reference for our implementation plans.
A large part of DMTN-030 is devoted to designing a topic-based documentation architecture. Following Every Page is Page One, topic-based documentation is organized as a network of self-contained pages that orient a reader who arrives from a web search, answers the reader’s question, and lets them move to related information with links. Unlike a linearly structured manual, topic-based documentation works naturally on the web. Some advantages of topic-based docs:
- Topics follow predefined types. This makes contributing documentation easier because we’ll provide templates and style documentation for every type of documentation we’ll need. As a developer, you’ll be able to contribute your knowledge without having to worry about how your content is organized.
- Since topics are self-contained, it’s easy to assign topic writing in JIRA tickets. It should be well understood what the scope and inter-topic relationships are before writing each topic. There will be less information duplication because topics link out to, rather than re-explain, subjects that are beyond their scope.
- The consistent presentation afforded by the type system will also improve reader’s wayfinding.
Combined with the doc-as-code approach, we think that topic-based documentation is an ideal system for documentation that is convenient for DM to manage, contribute to, and maintain.
DMTN-030 (v1) has the following sections:
- §1. Introduction.
- §2. Scope of the Science Pipelines documentation project.
- §3. The audiences of pipelines.lsst.io.
- §4. Documentation as code. Introduction to Git-level documentation organization, build, and deployment systems.
- §5. Topic-based documentation. Primer for topic-based writing.
- §6. Designing the homepage.
- §7. Processing topic type.
- §8. Framework topic type.
- §9. Module topic type.
- §10. Task topic type.
- §11. API reference documentation prototypes.
Soon, we will follow-up DMTN-030 with author documentation and ready-to-use templates so that we can finally begin to write the docs that DM needs.