Data Management should adopt a standard content style guide for user documentation. Specifically, I propose that we adopt the Google Developer Documentation Style Guide immediately with the understanding that we can "fork" that guide as our documentation efforts mature.

This style guide will help us write cohesively and effectively for our user-oriented documentation projects, such as https://pipelines.lsst.io. This style guide doesn't apply to what I call "project documentation" (technotes, LDMs, DMTRs, and so on) and academic papers.

Why we need a content style guide for user documentation

Organizations that create written content have (or should have) a content style guide. Style guides are fantastic resources for writers (in DM, everyone is a documentation writer) because they clearly spell out solutions to common writing issues. Like code style guides, content style guides streamline the review process. Since style guides are built from hard-won experience of technical communication teams, they guide authors towards best practices. Though some points in a style guide are seemingly arbitrary, many guidelines exist because they distinctly improve the clarity of content.

Documentation written according to a style guide is more cohesive because all authors adopt the same approach. Right now, we are writing documentation with a range of voices and styles. Some of us currently write documentation like an astronomy paper. Others write user documentation like a highly formal requirements document. The style guide will help us write with a singular voice that befits modern user-facing technical communication. Such consistent documentation is a great thing for our readers since there's less cognitive dissonance from one page to the next.

Why we should start with the Google Developer Documentation Style Guide

Picking up an existing style guide, rather than creating one from scratch, is a good idea since it lets us build upon the experience of other organizations. The technical writing team at Google is top-notch, and recently they released their content style guide under a Creative Commons Attribution 3.0 license. Anyone can freely access the style guide, and if we require, we can "fork" the Google Developer Documentation Style Guide and extend it for our distinct purposes.

The Google Developer Documentation Style Guide matches up well with most of DM's needs. Google writes for developers (think of their Cloud products) and have good patterns for writing API references and presenting example code to sophisticated audiences.

The LSST Project does, already, have a style guide (Project Publications Style Manual). The Project's guide is handy for writing project documentation, but it doesn't cover the unique content and voice requirements of user-facing technical documentation.

How we can start using the Google Developer Documentation Style Guide

I suggest that we begin using the Google Developer Documentation Style Guide as-is. In the Developer Guide, we'd have a page that more-or-less links to https://developers.google.com/style/. The page would also list our differences to the Google style.

The one significant difference I can identify now is that our Python method and function summaries are written in the imperative mood since this matches the scientific Python style, whereas Google writes method and function summaries in the present tense. That said, the "present tense style" could be useful to adopt for documenting other technologies, like HTTP endpoints.

I don't expect everyone to read and master the Google Developer Documentation Style Guide immediately. I do hope that people will browse it and learn from it. When there's a discussion in a code review about how to do something, the style guide should be the last word in most cases. If there's a deficiency in the style guide, we ought to talk about it collectively in #dm-docs or https://community.lsst.org, and we can incorporate those thoughts into our style guide page.

In the intermediate term, I envision us building up a word list that deals with the usage of LSST and astronomy's unique terminology.

In the long term, we may want to fork the Google Developer Documentation Style Guide and use its content, under the CC-BY 3.0 terms, to seed an LSST User Documentation Style Guide wholly within https://developer.lsst.io.