Coincident with the timeframe of the LSST 2016 Project & Community Workshop, I’ll be working on the DM-6199 Epic. That epic is tasked with developing https://pipelines.lsst.io as a true replacement for both our Doxygen- and Confluence-based documentation efforts for the Science Pipelines segment of the LSST Stack.
I’d like to draw upon the experience, knowledge, and opinions of the DM team while I do this. After all, the Science Pipelines documentation is essentially a manifestation of your work. Having everyone in Tucson for LSST 2016 will be a great opportunity for this.
This post is to trial balloon to see if there might be interest in this as I don’t have a formal agenda planned yet. My idea is to have a small, highly-engaged, group of DM Developers. I’d like a mix of folks from the groups that contribute to
lsst_apps. I’d like a few experienced Developers who know/wrote everything, but also my fellow junior devs who have fresh experience trying to learn and comprehend a Stack built by others.
I see this group working concertedly, filling walls with sticky notes / wireframe diagrams as we attempt to design the Science Pipelines documentation. You can think of it as a design sprint. I don’t anticipate documentation being pushed to GitHub during this sprint.
Some of the design topics include:
- Defining the fundamental concepts upon which the LSST Stack is built and designing a curriculum of tutorials/examples/exercises that can lead our users on the path from ‘newbie’ to ‘expert.’
- Designing the front page of the documentation site (for example, see http://docs.astropy.org): how can we portray the true structure of the Stack, across all it’s EUPS packages and Python module namespaces, to users.
- Designing the command line task documentation experience. What’s the most effective way to organize tasks, document task operations and configurations (including ‘re-targeting’). What hooks do we have into the code that can help us automate/single source some of task reference documentation.
I also don’t know how this design sprint would be scheduled. It may happen in evenings over drinks if the daytime sessions are packed. Let me know if you’d be interested in participating in this group.