Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-453

Reorganization of the DM Developer Guide

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      This is a proposal to improve the DM Developer Guide's (developer.lsst.io) content organization.

      The Developer Guide, in its modern form, is now over 2 years old. When we first set out to build the Developer Guide, we had a rough idea of what we wanted to put in it based on existing wiki pages. But since then, the Developer Guide has grown substantially (thanks to 28 contributors!). I'm finding more and more that it's becoming difficult to put new content into the existing topic hierarchy. To keep the Developer Guide healthy, I think it's time for us to invest in some content reorganization.

      The core of this proposal is a new set of top-level topic sections:

      • Team: This is for pages about the DM subsystem itself. Topics include the onboarding checklist, our culture and conduct standards, and subsites for individual teams (DRP has one, others can too).
      • Communication: This is for pages that document how DM communicates. Here we'll talk about Slack, community.lsst.org, Confluence, RFCs, RFDs, meetings/conferences, and Zenodo.
      • Project documentation: This is for pages that document how we create and maintain DM's project documents: change-controlled documents, papers, and technical notes. Note that topics about creating user documentation for software and services aren't in this section because I'm finding that user documentation is an intrinsically different activity in both an organizational and technical sense.
      • Work management: This is for pages that describe how we get work done and track it. Here we'd have an overview topic of our development workflow, and detailed pages about JIRA and our agile practices.
      • Coding: This is for pages that you'll refer to when you're working inside Data Management codebases. This section is split into subsections, where each subsection corresponds to a technology or product. For example, a C++ subsection, a Python subsection, and a Git/GitHub subsection. Within each subsection there will typically be a style guide with prescriptive guidelines for how you should/must use the technology, followed by descriptive pages meant to share knowledge and expertise (each topic page will be labeled as such). I also envision a "DM Stack" subsection where we can collect information specifically about working in our EUPS stack, such as packaging. DM's other products could get their own coding guides too.
      • Developer infrastructure: This is for pages that document DM's hosted developer services. Currently this section of the site only has NCSA-hosted infrastructure (like lsst-dev), but I'd like to expand it to include documentation for our other services like Jenkins and even the prototype science platform deployments.
      • Writing for users: This content doesn't exist yet, but this is where we'll have our user documentation style guide. These pages will help us write consistently for documentation sites like pipelines.lsst.io. My intention is to seed this with the Google Developer Documentation Style Guide. Documentation for how to technically contribute documentation for specific projects (like pipelines.lsst.io) will go into the corresponding Coding guide. Whether or not this section will eventually exist is the subject of other tickets/RFCs.

      See the attached PDF that maps out these sections, along with specific topics that I expect to go in them.

      Potential questions

      • Will URLs change? Yes, I'm proposing changes to page URLs to put content into the new topic hierarchy. This is also an opportunity to give us consistent URL conventions, like [hyphens for connecting words].
      • How do we mitigate the impact of URL changes? Whenever a page moves, I'll leave a redirect page where it originally existed. This will be done manually, though later on we intend to build a more automated approach for managing redirects in our Sphinx sites. I'll also search for links to developer.lsst.io pages in our other sites and documents and push updates when necessary.
      • Will existing pages get split apart? In some cases, yes, I'd like to split and refactor existing topic pages.
      • What is the timeline for this change? Once approved, I intend to implement these changes rapidly so that the new layout is available before DM's meeting in March.
      • I don't think my Topic X will fit in that hierarchy. If you have a Developer Guide topic in mind and you don't think it will work within this proposed organization, let me know. Let's work together to get this right.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

                • Assignee:
                  jsick Jonathan Sick
                  Reporter:
                  jsick Jonathan Sick
                  Watchers:
                  Bill Glick, David Shupe, Gabriele Comoretto, Jim Bosch, John Swinbank, Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness, Wil O'Mullane, Xiuqin Wu
                • Votes:
                  2 Vote for this issue
                  Watchers:
                  11 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Planned End:

                    Summary Panel