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.