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!

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.

Superseded by DM-10637.