Proposal: Science Pipelines Documentation Design Workshop at LSST2016

Data Management
#1

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.

1 Like
#2

This is exactly the kind of thing we should be doing in the DM hack sessions.

#3

Certainly, though I have slightly different goals than a DM-wide hack session:

  • I’d like the group to be small enough so that there’s only one conversation thread happening at a time so that I can personally hear and understand everything that’s going on.
  • No code should be committed during these sessions. It’s really about finding a tangible design.
#4

I think this is a great idea, and I’d love to participate.

1 Like
#5

I think I’d like to participate too. I think I make a good “complaining newbie”.

1 Like
#6

I’d be interested in participating, with the caveat that I understand @jsick’s hope is to convene a relatively small group: to help make that possible, I’d be keen to cede my place to a non-DMLT, non-management developer who has ideas that should get heard.

1 Like