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

Create a living DM user documentation content style guide

    XMLWordPrintable

    Details

      Description

      Early experience from creating pipe_base documentation has shown that we need a user documentation content style guide to help us effectively produce consistent and high-quality documentation for end-users.

      This style guide becomes a place to:

      • Discuss tone and voice for specific types of end-user documentation and share technical writing advice.
      • List preferred spellings, especially for domain-specific words. For example, "subtask" or "sub-task" — I've seen both in existing documentation. We need to decide on one. We also need a place to remind use that it's spelled "GitHub."
      • Discuss grammar and style issues beyond what is already in the Project Publications Style Manual.

      The intent of the user documentation style guide is to respectfully build upon the Project Publications Style Manual. The DM user documentation style guide's default stance should be to inherit the recommendations of the Project style guide. In rare occasions, we may need to override its advice to adopt best practices specific to end-user documentation writing. It's possible that the DM user documentation style guide's recommendations could eventually get moved to Project Publications Style Manual, but I think we will always need a style guide specifically for user documentation because of the unique requirements of user documentation compared to management documentation and scientific articles.

      This ticket will seed the user documentation content style guide as a sub-section of the DM Developer Guide.

        Attachments

          Issue Links

            Activity

            jsick Jonathan Sick created issue -
            jsick Jonathan Sick made changes -
            Field Original Value New Value
            Epic Link DM-10635 [ 32584 ]
            jsick Jonathan Sick made changes -
            Description Early experience from creating {{pipe_base}} documentation has shown that we need a *user documentation content style guide* to help us effectively produce consistent and high-quality documentation for end-users.

            This style guide becomes a place to:

            - Discuss tone and voice for specific types of end user documentation and share technical writing advice.
            - List preferred spellings, especially for domain-specific words. For example, "subtask" or "sub-task" — I've seen both in existing documentation. We need to decide on one. We also need a place to remind use that it's spelled "GitHub."
            - Discuss grammar and style issues beyond what is already in the [Project Publications Style Manual|https://ls.st/Document-13016].

            The intent of the user documentation style guide is to respectfully build upon the [Project Publications Style Manual|https://ls.st/Document-13016]. The DM user documentation style guide's default stance should be to inherit the recommendations of the Project style guide. In rare occasions, we may need to override its advice for the sake of high-quality end user documentation. It's possible that the DM user documentation style guide's recommendations could eventually get moved to [Project Publications Style Manual|https://ls.st/Document-13016], but I think we will always need a style guide specifically for user documentation because of the unique requirements of user documentation compared to management documentation and scientific articles.

            This ticket will seed the user documentation content style guide as a sub-section of the [DM Developer Guide|https://developer.lsst.io].
            Early experience from creating {{pipe_base}} documentation has shown that we need a *user documentation content style guide* to help us effectively produce consistent and high-quality documentation for end-users.

            This style guide becomes a place to:

            - Discuss tone and voice for specific types of end-user documentation and share technical writing advice.
            - List preferred spellings, especially for domain-specific words. For example, "subtask" or "sub-task" — I've seen both in existing documentation. We need to decide on one. We also need a place to remind use that it's spelled "GitHub."
            - Discuss grammar and style issues beyond what is already in the [Project Publications Style Manual|https://ls.st/Document-13016].

            The intent of the user documentation style guide is to respectfully build upon the [Project Publications Style Manual|https://ls.st/Document-13016]. The DM user documentation style guide's default stance should be to inherit the recommendations of the Project style guide. In rare occasions, we may need to override its advice for the sake of high-quality end user documentation. It's possible that the DM user documentation style guide's recommendations could eventually get moved to [Project Publications Style Manual|https://ls.st/Document-13016], but I think we will always need a style guide specifically for user documentation because of the unique requirements of user documentation compared to management documentation and scientific articles.

            This ticket will seed the user documentation content style guide as a sub-section of the [DM Developer Guide|https://developer.lsst.io].
            jsick Jonathan Sick made changes -
            Description Early experience from creating {{pipe_base}} documentation has shown that we need a *user documentation content style guide* to help us effectively produce consistent and high-quality documentation for end-users.

            This style guide becomes a place to:

            - Discuss tone and voice for specific types of end-user documentation and share technical writing advice.
            - List preferred spellings, especially for domain-specific words. For example, "subtask" or "sub-task" — I've seen both in existing documentation. We need to decide on one. We also need a place to remind use that it's spelled "GitHub."
            - Discuss grammar and style issues beyond what is already in the [Project Publications Style Manual|https://ls.st/Document-13016].

            The intent of the user documentation style guide is to respectfully build upon the [Project Publications Style Manual|https://ls.st/Document-13016]. The DM user documentation style guide's default stance should be to inherit the recommendations of the Project style guide. In rare occasions, we may need to override its advice for the sake of high-quality end user documentation. It's possible that the DM user documentation style guide's recommendations could eventually get moved to [Project Publications Style Manual|https://ls.st/Document-13016], but I think we will always need a style guide specifically for user documentation because of the unique requirements of user documentation compared to management documentation and scientific articles.

            This ticket will seed the user documentation content style guide as a sub-section of the [DM Developer Guide|https://developer.lsst.io].
            Early experience from creating {{pipe_base}} documentation has shown that we need a *user documentation content style guide* to help us effectively produce consistent and high-quality documentation for end-users.

            This style guide becomes a place to:

            - Discuss tone and voice for specific types of end-user documentation and share technical writing advice.
            - List preferred spellings, especially for domain-specific words. For example, "subtask" or "sub-task" — I've seen both in existing documentation. We need to decide on one. We also need a place to remind use that it's spelled "GitHub."
            - Discuss grammar and style issues beyond what is already in the [Project Publications Style Manual|https://ls.st/Document-13016].

            The intent of the user documentation style guide is to respectfully build upon the [Project Publications Style Manual|https://ls.st/Document-13016]. The DM user documentation style guide's default stance should be to inherit the recommendations of the Project style guide. In rare occasions, we may need to override its advice to adopt best practices specific to end-user documentation writing. It's possible that the DM user documentation style guide's recommendations could eventually get moved to [Project Publications Style Manual|https://ls.st/Document-13016], but I think we will always need a style guide specifically for user documentation because of the unique requirements of user documentation compared to management documentation and scientific articles.

            This ticket will seed the user documentation content style guide as a sub-section of the [DM Developer Guide|https://developer.lsst.io].
            jsick Jonathan Sick made changes -
            Status To Do [ 10001 ] In Progress [ 3 ]
            jsick Jonathan Sick made changes -
            Story Points 0.5
            jsick Jonathan Sick made changes -
            Epic Link DM-10635 [ 32584 ] DM-5646 [ 23496 ]
            jsick Jonathan Sick made changes -
            Epic Link DM-5646 [ 23496 ] DM-7500 [ 26629 ]
            jsick Jonathan Sick made changes -
            Epic Link DM-7500 [ 26629 ] DM-12790 [ 36408 ]
            jsick Jonathan Sick made changes -
            Epic Link DM-12790 [ 36408 ] DM-14522 [ 86285 ]
            jsick Jonathan Sick made changes -
            Epic Link DM-14522 [ 86285 ] DM-5403 [ 23210 ]
            jsick Jonathan Sick made changes -
            Link This issue relates to RFC-555 [ RFC-555 ]
            jsick Jonathan Sick made changes -
            Link This issue is triggered by RFC-555 [ RFC-555 ]
            jsick Jonathan Sick made changes -
            Epic Link DM-5403 [ 23210 ] DM-16933 [ 238280 ]
            jsick Jonathan Sick made changes -
            Story Points 0.5 1
            frossie Frossie Economou made changes -
            Status Admin Review [ 3 ] In Progress [ 11605 ]
            frossie Frossie Economou made changes -
            Status Review [ 11605 ] In Progress [ 3 ]
            afausti Angelo Fausti made changes -
            Reviewers Angelo Fausti [ afausti ]
            Status In Progress [ 3 ] In Review [ 10004 ]
            afausti Angelo Fausti made changes -
            Status In Review [ 10004 ] Reviewed [ 10101 ]
            jsick Jonathan Sick made changes -
            Story Points 1 1.7
            jsick Jonathan Sick made changes -
            Resolution Done [ 10000 ]
            Status Reviewed [ 10101 ] Done [ 10002 ]

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Reviewers:
              Angelo Fausti
              Watchers:
              Angelo Fausti, David Shupe, Jonathan Sick, Krzysztof Findeisen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.