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

Documentation conventions for utilities and scripts

    Details

    • Type: Story
    • Status: To Do
    • Resolution: Unresolved
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      The Science Pipelines codebase contains a bunch of useful utilities and scripts. These tend to be dumped in example or bin directories with minimal explanation — they are easily forgotten even by the people who wrote them, and are unlikely ever to be found by others to whom they might be useful.

      An example is the skymap/examples/showVisitSkymap.py script.

      Material of this sort isn't (obviously, at least) covered by the pipelines documentation architecture described in DMTN-030.

      Please provide some guidance about how we should make scripts like this more discoverable.

        Attachments

          Issue Links

            Activity

            Hide
            swinbank John Swinbank added a comment -

            (I think this falls in the realm of Jonathan Sick, but obviously please reassign if you disagree!)

            Show
            swinbank John Swinbank added a comment - (I think this falls in the realm of Jonathan Sick , but obviously please reassign if you disagree!)
            Hide
            swinbank John Swinbank added a comment -

            At least in the short term, I suggest that we value expediency above correctness. For example, could we just create a page on pipelines.lsst.io called “useful scripts” and ask folks to dump a link to their script and a brief description of what it does there? Long term, we should curate this properly (and CI the scripts...), but this seems like a super-low-effort to do better than we're doing at the moment.

            Show
            swinbank John Swinbank added a comment - At least in the short term, I suggest that we value expediency above correctness. For example, could we just create a page on pipelines.lsst.io called “useful scripts” and ask folks to dump a link to their script and a brief description of what it does there? Long term, we should curate this properly (and CI the scripts...), but this seems like a super-low-effort to do better than we're doing at the moment.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                swinbank John Swinbank
                Watchers:
                Frossie Economou, John Swinbank, Robert Lupton
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Summary Panel