Fix Version/s: None
Component/s: Stack Documentation and UX
Jim Bosch wrote an excellent tutorial on command line data processing with HSC data. This is the type of content that’s sorely needed to get new users up to speed with LSST processing.
Naturally this content belongs in the lsst_apps documentation project, whose URL is currently https://pipelines.lsst.io. I think this tutorial can serve as a nucleus for a set fo ‘First Steps’ tutorials that serve as primers for lsst_apps before a user dives deeper into the tutorials and API references associated with each package.
With that, this ticket will
1. Migrate DMTN-023’s content to the https://github.com/lsst/pipelines_docs repo and deprecate DMTN-023 (with a link to follow-up)
2. Create a new section in https://pipelines.lsst.io for introductory tutorials
3. Migrate the content
4. Improve the tutorial’s content and presentation were possible.
|Field||Original Value||New Value|
|Watchers||Jonathan Sick [ Jonathan Sick ]||Frossie Economou, Jim Bosch, Jonathan Sick [ Frossie Economou, Jim Bosch, Jonathan Sick ]|
Hi John Swinbank, point taken. I hope that Mandeep can attend the LSST Project and Community workshop and that we (and maybe a couple other key folks) can sit down for a few days and plan out the docs and try some things out with the content we have.
I should clarify the real purpose of this ticket. I see point #4 as being the most important. Jim has given us some great content (in much the same was as the HSC docs are great content), but I want to take the opportunity in this ticket to explore choices of structure, style & tone, testability, etc. given the original content. I see this as being hugely important, especially early on. What is the appropriate tone and structure for tutorials? I don't know, but the point of this ticket is to help me apply best practices from conferences like Write the Docs and content strategy books and figure this out. Once we establish a style for our documentation, it'll be easier for our expert developers to contribute effective documentation. If we don't establish meaningful tone and structure, I'm worried that there's a possibility we'll accidentally end up with user-hostile documentation (I can give a few examples of this already in the LSST space, but there's no need to point fingers).
Jim's tutorial probably won't be inserted into the Pipelines docs unchanged, nor will the HSC docs be inserted in the Pipelines docs unchanged. What's important to me is that we have technically correct content that I can now craft into a well-architected LSST Pipelines documentation project.
Furthermore, I don't see Jim's tutorial being the only Pipelines tutorial. We need to offer many tutorials, on many topics, at many levels of sophistication. Jim's tutorial is just the beginning; the HSC docs will provide additional layers of documentation, and there's lots more original content that needs to be created. Yes there's overlap in content, and part of the editorial design work that needs to be done is figuring out how to refactor the content into a meaningful series of coherent tutorials that couple with reference documentation for packages.
I believe that documentation is an activity inherent to all WBSs and community open source contributions, and I'm really excited by contributions from folks writing technotes and community contributions like Mandeep's work on the HSC docs. However, I'd like to be granted agency to act as an overall editor and curator of LSST user documentation.
cc'ing Frossie Economou since this is partially a T/CAM-level issue.
Jonathan Sick already asked Mandeep on HipChat if he'll be at the PCW. That might be a good time to get a group together and start brainstorming around the issues Jonathan refers to above.
|Resolution||Done [ 10000 ]|
|Status||To Do [ 10001 ]||Invalid [ 11005 ]|
Hi Jonathan Sick – as you know, Mandeep Gill has been working on very similar tutorial-style documentation, based on the existing HSC docs. It's unfortunate that the timing wasn't right for Jim to be able to pick up his work rather than putting this together himself. However, before we simply adopt Jim's work, we should carefully discuss the situation with Mandeep – both to ensure we're getting the highest quality set of (merged?) documentation possible, and also to ensure his nose isn't left out of joint by having his work effectively superseded before it's even begun!