Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-25784

Update documentation for ts_ATDome to match our new template

    Details

    • Story Points:
      1
    • Sprint:
      TSSW Sprint - Jul 6 - Jul 20, TSSW Sprint - Jul 20 - Aug 3
    • Team:
      Telescope and Site
    • Urgent?:
      No

      Description

      Try out the new documentation format on a small package: ts_ATDome.

        Attachments

          Issue Links

            Activity

            Hide
            rowen Russell Owen added a comment - - edited

            Pull request: https://github.com/lsst-ts/ts_ATDome/pull/29

            I confess I did not follow the template strictly for several reasons:

            • I very strongly feel that the most important information should be on the main page. I would argue that is the information for users.
            • I tweaked things a little to enhance information density, especially making Configuration, etc. subsections of User Guide.
            • I prefer having the Version History as the last item on the page (though I wish we could link to it directly instead of having to go to the end of the main page).
            • The suggested (invisible) section anchors will not work if we ever link the docs, as I expect we will someday. I added a _lsst.ts.ATDome prefix to each one
            • I removed the CSC name from the buttons in the bar at the top. It is needless repetition and obscures what the buttons actually do.
            • I strongly suggest having the most important buttons to the left. I put XML ("SAL Interface") first, github second, Jira last (and would have put Jenkins next to Jira if this package had a Jenkins build).

            The button bar is a nice touch. However, I chose not to duplicate it for the developer's page. Duplicated information is hard to maintain. There may be a way to define it in one place and duplicate it in the other.

            I really like having the developer's guide as a separate page.

            As to layout: I did not make any subdirectories. I feel that's only worth considering if we end up with many pages.

            Pull request: https://github.com/lsst-ts/ts_ATDome/pull/29
            Built docs: https://ts-atdome.lsst.io/v/DM-25784/index.html

            Show
            rowen Russell Owen added a comment - - edited Pull request: https://github.com/lsst-ts/ts_ATDome/pull/29 I confess I did not follow the template strictly for several reasons: I very strongly feel that the most important information should be on the main page. I would argue that is the information for users. I tweaked things a little to enhance information density, especially making Configuration, etc. subsections of User Guide. I prefer having the Version History as the last item on the page (though I wish we could link to it directly instead of having to go to the end of the main page). The suggested (invisible) section anchors will not work if we ever link the docs, as I expect we will someday. I added a _lsst.ts.ATDome prefix to each one I removed the CSC name from the buttons in the bar at the top. It is needless repetition and obscures what the buttons actually do. I strongly suggest having the most important buttons to the left. I put XML ("SAL Interface") first, github second, Jira last (and would have put Jenkins next to Jira if this package had a Jenkins build). The button bar is a nice touch. However, I chose not to duplicate it for the developer's page. Duplicated information is hard to maintain. There may be a way to define it in one place and duplicate it in the other. I really like having the developer's guide as a separate page. As to layout: I did not make any subdirectories. I feel that's only worth considering if we end up with many pages. Pull request: https://github.com/lsst-ts/ts_ATDome/pull/29 Built docs: https://ts-atdome.lsst.io/v/DM-25784/index.html
            Hide
            rowen Russell Owen added a comment -

            Reviewed on github

            Show
            rowen Russell Owen added a comment - Reviewed on github

              People

              • Assignee:
                rowen Russell Owen
                Reporter:
                rowen Russell Owen
                Reviewers:
                Patrick Ingraham
                Watchers:
                Eric Coughlin, Patrick Ingraham, Russell Owen
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: