This is a design sprint to kick off the LSST Science Pipelines documentation reboot. Our goal is to a create a tangible vision of what the Science Pipelines documentation will be. Questions we want to answer are:
- Who are the users of Science Pipelines documentation? What does each group want to get out of the Science Pipelines and its documentation? Do those needs conflict? Do we need to prioritize one user group in the initial implementation?
- What are the boundaries of the Science Pipelines documentation (the site at https://pipelines.lsst.io What are adjacent documentation projects that the Science Pipelines documentation might link against?
- What's the curriculum for learning the Science Pipelines? What are the concepts that the Science Pipelines documentation site needs to cover? How are these concepts organized (hierarchically or as a bottom-up information network). Do different types of users need specific entry points into the documentation and Science Pipelines itself?
- What kinds of content are we going to be producing? What do the templates of these topic types look likes?
- How are concepts unique to Science Pipelines, like tasks and command line tasks, documented in both a code and information architecture sense?
Intended Sprint Products
These are suggested products and outcomes from the sprint:
- A map of the science pipelines site. This map should resolve into individual HTML/reStructuredText documents (topics in Every Page is Page One terminology). Each topic should be annotated with:
- Topic name.
- Content purpose and scope.
- Topic type (i.e., template).
- Adjacent topics (topics that link into this page; topics this page will link out to).
- Topic types and templates. Each template shapes how different types of topics are written. Examples can be: API reference, task, command line task, tutorial project, conceptual overview, recipe. See Every Page is Page One Chapter 9: EPPO Topics Conform to a Type.
- Timelines. Timeline for content and for documentation infrastructure.
Prep Work/Background Reading Material
- Read Every Page is Page One.
- Jonathan Sick's "Pipelines Documentation Site Organization Sketch" is on clo.
- LDM-493: Data Management Documentation Architecture.
- Potentially relevant design docs, which may be cross-referenced with or otherwise relate to Science Pipelines docs:
- validate-base documentation
- Astropy documentation
- Tuesday December 6: campfire chat at Bentley's or elsewhere.
- Wednesday December 7. 9:00 am to 5:00 pm. LSST Workroom.
- Thursday December 8. 9:00 am to 5:00 pm. LSST Workroom.
- Friday December 9. 9:00 am to 5:00 pm (or as participants depart). LSST Workroom.
What is the scope of the "Science Pipelines" documentation site?
Boundary between Pipelines docs and the Developer Guide
Should the pipelines documentation cover developer and build-oriented topics currently in the DM Developer Guide? Do pipelines users need to be able to create Stack packages to make Level 3 data products?
|Science Pipelines docs and LDM-151|
Who are our users?
EUPS Packages as units of organization
What is the structure of the documentation homepage?
Where should concepts of science interest (such as algorithm details) be documented?
How should examples and tutorials be produced?
We need additional prototyping and design discussion before we identify a pattern for producing and testing examples in documentation.
How should C++/Python API reference documentation be produced?
Listing topic types and templates
Task topic type.
README topic type + GitHub summary line.
Measurement framework topic example
Butler framework topic example.
|Community.lsst.org and the docs|
|Tagging command line tasks|
We'll have lots of lists of command line tasks in two places: module topic pages and in processing context sections of the home page.
|Task configuration and re-targetting|
|Command line task topic types vs task topic types|
Task framework documentation should document the philosophy of tasks vs command line tasks
|Measurement extensions listing||We can look at the registry of measurement plugins (extensions)|
Important/interesting frameworks are the ones that span multiple modules
Command line tasks
- Generating coadds:
- Multi-band processing:
- ctrl_pool middleware tasks:
More things to discuss/design
- Task list topic types
- Troubleshooting (when something goes wrong). -> integrate into task lists, and into task reference pages.
- Turn pipelines_docs into an EUPS package so it can use lsst.utils.getPackageDir rather than assuming that packages are in lsstsw
- Integrate doc builds with sconsUtils
- Branch dashboard pages