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

Coordinate policy about google docs

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      Per discussion on Sept 1st (mtg note here), we shoulid coordinate defining policies related to google docs and ensure they are clearly documented. Main issue: stories/epics are closed, they point to google docs that are scattered at random places. Google docs are fine for collaborative doc writing, but official/final versions should be transferred to official DM repositories

        Attachments

          Issue Links

            Activity

            Hide
            womullan Wil O'Mullane added a comment -

            There is an LSST policy - it is quite clear, documents must be published as PDF to Docushare.
            For DM I would also like doc source to be in GitHub preferable in TeX for design/technical docs and MD for the user facing manuals. source code docs. If a Google doc is used then Put a word doc in a GitHub within the structure defined in LDM-294 section 2.1

            Show
            womullan Wil O'Mullane added a comment - There is an LSST policy - it is quite clear, documents must be published as PDF to Docushare. For DM I would also like doc source to be in GitHub preferable in TeX for design/technical docs and MD for the user facing manuals. source code docs. If a Google doc is used then Put a word doc in a GitHub within the structure defined in LDM-294 section 2.1
            Hide
            tjenness Tim Jenness added a comment -

            Yes. It's clear what the end game is. We've been very bad at getting there. We can treat Google docs as intermediate source if the authors are doing heavy collaboration and are more familiar with Word than Latex. The problem is where to go next with them. The Google docs tend to grow organically and don't have the standard LSST document style in most cases (see LPM-51 for style references). Some of the google docs attached to tickets could be tech notes. NCSA have grown in to generating many Google docs for operations planning and we need a plan for getting those into a suitable format for docushare. One thing to bear in mind is that generating a PDF from the google doc means the google doc has to stay around if editing is required in the future. I agree that a Word doc should be exported and stored somewhere to prevent the original source from disappearing.

            One aside: in my previous project we got into the habit of uploading PDFs to the document repository but with the Word doc attached to the PDF itself.

            I'll see if I can get JIRA to tell me all the tickets with google docs.

            Show
            tjenness Tim Jenness added a comment - Yes. It's clear what the end game is. We've been very bad at getting there. We can treat Google docs as intermediate source if the authors are doing heavy collaboration and are more familiar with Word than Latex. The problem is where to go next with them. The Google docs tend to grow organically and don't have the standard LSST document style in most cases (see LPM-51 for style references). Some of the google docs attached to tickets could be tech notes. NCSA have grown in to generating many Google docs for operations planning and we need a plan for getting those into a suitable format for docushare. One thing to bear in mind is that generating a PDF from the google doc means the google doc has to stay around if editing is required in the future. I agree that a Word doc should be exported and stored somewhere to prevent the original source from disappearing. One aside: in my previous project we got into the habit of uploading PDFs to the document repository but with the Word doc attached to the PDF itself. I'll see if I can get JIRA to tell me all the tickets with google docs.
            Hide
            tjenness Tim Jenness added a comment -

            Depending on the direction you want to go, pandoc does a pretty good job of converting Word docx files to latex such that we can quickly insert the standard LSST preamble to the beginning.

            Show
            tjenness Tim Jenness added a comment - Depending on the direction you want to go, pandoc does a pretty good job of converting Word docx files to latex such that we can quickly insert the standard LSST preamble to the beginning.
            Hide
            tjenness Tim Jenness added a comment -

            Tickets with google docs delivered: DM-6432 (tech report), DM-4315 (instruction manual), DM-6433 (tech report), DM-7322 (Tech report), DM-6431 (tech report), DM-2000 (tech report qserv replication), DM-6671 (conops), DM-6882 (conops), DM-9484 (analysis), DM-9480 (header proposal).

            That was from a quick search. There are many more conops documents around.

            Show
            tjenness Tim Jenness added a comment - Tickets with google docs delivered: DM-6432 (tech report), DM-4315 (instruction manual), DM-6433 (tech report), DM-7322 (Tech report), DM-6431 (tech report), DM-2000 (tech report qserv replication), DM-6671 (conops), DM-6882 (conops), DM-9484 (analysis), DM-9480 (header proposal). That was from a quick search. There are many more conops documents around.
            Hide
            tjenness Tim Jenness added a comment -

            I can confirm that "MD" above is meant to be restructured text.

            Show
            tjenness Tim Jenness added a comment - I can confirm that "MD" above is meant to be restructured text.
            Hide
            tjenness Tim Jenness added a comment -

            I think we should put this agreed policy into the new LDM-294.

            Show
            tjenness Tim Jenness added a comment - I think we should put this agreed policy into the new LDM-294.
            Hide
            tjenness Tim Jenness added a comment -

            Project-wide policy on Google Docs is being included in an update to LPM-51 as part of LCR-933.

            Show
            tjenness Tim Jenness added a comment - Project-wide policy on Google Docs is being included in an update to LPM-51 as part of LCR-933 .

              People

              • Assignee:
                womullan Wil O'Mullane
                Reporter:
                jbecla Jacek Becla
                Watchers:
                Gregory Dubois-Felsmann, John Swinbank, Jonathan Sick, Paul Domagala [X] (Inactive), Tim Jenness, Wil O'Mullane
              • Votes:
                1 Vote for this issue
                Watchers:
                6 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel