Details
-
Type:
Story
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: Stack Documentation and UX
-
Labels:
-
Story Points:1.7
-
Epic Link:
-
Team:SQuaRE
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
| Field | Original Value | New Value |
|---|---|---|
| Epic Link |
|
| 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]. |
| 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]. |
| Status | To Do [ 10001 ] | In Progress [ 3 ] |
| Story Points | 0.5 |
Hmm... the former describes itself as developer documentation, not end-user documentation. Does that mean our end-users are third-party developers? (Please answer this question in the style guide!)
Krzysztof Findeisen
added a comment - Hmm... the former describes itself as developer documentation, not end-user documentation. Does that mean our end-users are third-party developers? (Please answer this question in the style guide!) Krzysztof Findeisen, the Google style guide is suited for any kind of technical documentation.
When they say "developer documentation," Google is talking about the developers who use and build upon their products (an example of their end-user documentation is https://kubernetes.io/docs/home/). This matches up well with LSST where our audience is also fairly technical: astronomers using our data releases and astronomer-engineers building upon our software.
The new focus of this ticket is to specifically implement RFC-555:
- Add a new page/area to https://developer.lsst.io that represents the homepage the the "DM user documentation style guide"
- Link to the Google Developer Documentation Style Guide as the basis of our own style.
- Announce the new style guide and recommended usage on https://community.lsst.org.
| Story Points | 0.5 | 1 |
| Status | Admin Review [ 3 ] | In Progress [ 11605 ] |
| Status | Review [ 11605 ] | In Progress [ 3 ] |
| Reviewers | Angelo Fausti [ afausti ] | |
| Status | In Progress [ 3 ] | In Review [ 10004 ] |
Looks great! The page has information and links to user documentation style guide in the DM developer guide. It clarifies where to use the style guide and contexts where the style guide does not apply.
| Status | In Review [ 10004 ] | Reviewed [ 10101 ] |
| Story Points | 1 | 1.7 |
| Resolution | Done [ 10000 ] | |
| Status | Reviewed [ 10101 ] | Done [ 10002 ] |
Two user documentation style guides that are open source (CC-BY licensed) are:
I think it'd be a good to directly port relevant pages from the Google style guide to form the beginnings of the LSST User Documentation Style Guide. I like Google's docs and I think their style and tone match what I hope to build at LSST.