What are our highest documentation priorities?

We held a meeting and took a straw poll at the end. The results are (with number of votes following the #)

  1. Create an annotated Table of Contents # 6
  2. The Butler; what it is, how to use it, and what it supports for any given camera # 6
  3. How do I make a gri three-colour diagram from a e.g. HSC visits in gri? # 3
  4. How do I use Jira and github to shepherd an issue from inception to Done? # 3
  5. How should I use our cmdLineTasks to generate coadds? # 3
  6. How do I set things up for remote visualisation of data (ds9 and notebooks)? # 2
  7. What are all the Tasks, and how do I use them? (N.b. much of this is in doxygen) # 2
  8. How do I add a new measurement algorithm (N.b. JFB’s bootcamp talk) # 2
  9. Description of all the measurement plugins, including their algorithms. # 1
  10. How do I generate a catalogue from a flat-fielded FITS file? # 0
  11. How do I make a set of flat fields? # 0

We also noted that Steve Bickerton had a lot of useful documentation at
and that the Q&A page at
has lots of useful things that should be migrated to Community.

1 Like

This is not a public page.

I think you can generate your own login at :8080. If not, I’ll get it fixed.

This could mean a lot of (different) things to a lot of people. What does it mean to you?

I think I know, but it’s a @jbosch suggestion so I’ll let him answer.

Here are some more, though these are strictly doxygen:

  • Many tasks are still missing thorough documentation and don’t appear on the tasks page at all
  • Some packages, including most obs_* packages, are missing a doc directory, so I doubt their Doxygen is ever generated
  • Many packages are missing a main.dox page and so don’t appear on the main doxygen page; I suggest we require that every package have one, and that it give a reasonable overview of the contents
1 Like

I had in mind a curated single entry point that organizes the high-level documentation we already have, including:

Some of these probably deserve direct links from a single top-level page, others might be an intermediate page away. And of course the number and organization of intermediate pages will naturally evolve.

There’s a lot I could imagine also being linked from that page (including the other topics being discussed here), but I wanted to start but just making it easier to find the best documentation we have already written.

1 Like

Thanks for this list @RHL!

You have my assurances that this is a given. The information architecture of LSST DM, to this point, is a little horrendous. The New Docs will absolutely have a unified architecture that is logical and easy to follow. Right now there are so many hidden corner’s in DM’s documentation that it’s completely impossible to expect anyone from the community to reliably discover any piece of information about our work. Note that a lot of this will happen by pulling information out of Confluence and doxygen and unifying them in a single doc platform.

I’ve also grown to appreciate the usefulness of the Design Documents as part of my reStructuredText conversion exercise. I’d love to have all the Design Documents available as websites, and organized about a Design Document Library. Since everything will be HTML, it will be easy for the Stack Docs, and other resources, to deeply link into the Design Docs.

I think this work will involve overhauling http://dm.lsst.org and making it an integral part of the Stack experience.

Okay, so this seems to be the most wanted fundamental document. I’ll happily make this a priority.

Yes, as a Stack Newbie I’ve found the existing developer documentation to have lots of holes and worrying deprecation warnings. I do plan to make a Developer Workflow Guide a priority.

Aside from user guides for Tasks and Measurement Algorithms, it seems that a lot of the other priorities, at least as posed here, seem to be best framed as tutorials. In that case it may be worth it for me to put together at least one tutorial to establish the format, and then invite the rest of DM to contribute more tutorials.

That’s a terrific resource. It seems that Steve’s docs are organized around recipes/tutorials, and I’ll look into seeing what could be forked and repackaged into tutorials for the New Docs.

But keep in mind that tutorials and recipes are just one aspect of the New Docs; the New Docs also needs to user guides that explain stack concepts and architectures, and include API references (what we’ve used doxygen for in the Old Docs.)

I think the best/only way to migrate this sort of content onto Community is to have people re-ask relevant questions and have others re-answer them. You could make it a hack day exercise.

I don’t see why this is the best/only way. There are a bunch of questions, and a number of them need answers on the LSST side. So isn’t it migrating the content to the proper place in LSST exactly the sort of thing that our documentation expert should be doing? It’s not clear to me that an ever-growing FAQ is the answer.

Migrating to community.lsst.org while maintaining authorship of both questions and answers is I think difficult without just re-asking/re-answering (presumably via cut and paste). Without authorship, we can get the content but lose some community benefits. (Some of that occurred with our attempt at Confluence Questions.)

Migrating answers to some other location in the documentation or making answers already in the documentation more discoverable are different matters, of course.

1 Like

I don’t think we need preserve ownership. I’d like to see this content migrated as a documentation task.