We need a Style Guide for both docs and code

[saberbrasher]

It has come up multiple times, in various places, that we should have a style guide for each of our primary content types (docs and code). This was touched on here: #1200 (with many other suggestions that have since been addressed) so I thought it should have a focused issue for discussion.

@andypbarrett and I envision two style guides, one for our documentation, and one for code-based content. Both of them would live under the "Reference" section of our Contributor guide. We want these to be a tool that makes it as easy as possible for folks to contribute (and will hopefully cut down on review time if the guides serve well).

To start the conversation, a few questions:

1. What are absolute "need to haves" in each of these style guides?
2. Are there some great style guides that you can think of that we should emulate?
3. Additional thoughts on how you have used such guides with other projects/ libraries?

Thanks in advance to anyone who jumps in!

[mfisher87]

Additional thoughts on how you have used such guides with other projects/ libraries?

A style guide I built for a full-day workshop at AGU 2025: https://agu2025.workshops.geojupyter.org/for-instructors/style-guide/

need to haves

What I've got off the dome right now; I'll try and edit with more. These are my opinions based on experience, of course not claiming that these are all "correct" :)

Docs

• Diataxis as a mental framework and best practices for writing docs (of course!) -- specifically call out some really important tenets. E.g. which key principles of tutorials are most important/challenging for this project and should stay at top of mind?
• Prefer short pages over long pages -- long pages are a signal maybe they should be busted up in to smaller chunks.
• Prefer short sentences
• Prefer short paragraphs
• Use lots of subheadings
• Use callouts in moderation. Too many callouts is noisy. Too few callouts and important information blends in with other prose.
• Prefer callouts over emphasis (bold/italic/whatever). Shouldn't be applied universally, but emphasis can be a signal that a callout may be useful.
• Use callouts consistently -- set criteria for when to use warning, hint, note, important types. Perhaps rule out using "hint" at all, use "note" instead.
• Use collapsed callouts for stuff that's not critical to the main content. Collapsed callouts may be a signal that the content should go in an Explanation page.
• NO TITLE CASE :) unless referencing a proper noun.

Code

• Liberally use keyword-only arguments! If a function/method has multiple parameters, you probably want keyword-only arguments. You may even want kw-only arguments for single-arg functions, but IMO that's a signal the function needs a better name (more detail here Apply a consistent standard for keyword-only arguments and remove FBT noqas #1356)
• Defensively quote all YAML strings (Style guide proposal: defensively quote _all_ YAML strings #878)
• Readability is approximately the most important thing. Code is read more than it's written
• Apply principle of least astonishment
• Apply single-responsibility principle
• Naming is super important and helps with readability and applying the single responsibility principle. Code is read more than it's written
  • Always use verb-prefixed boolean names, e.g. isDope, hasTheFlu, canJuggle, shouldGoToTherapy, didEatBreakfast (https://thatamazingprogrammer.com/posts/stop-naming-your-variables-flag-the-art-of-boolean-prefixes/)
  • Always use positive boolean names, e.g. isEnabled ✔️ -- isDisabled ಠ_ಠ
  • Always use booleans to represent single piece of boolean state instead of composite state. We have a good amount of this in our codebase. You can have a composite boolean if it combines other booleans and has a very explicit name. See the multi-purpose boolean example in this article
  • Prefer clarity over succinctness. If you need a long function name to make its behavior/responsibility clear, do it and don't look back. Long names are OK. We all have autocomplete. Code is read more than it's written
• Docstrings everywhere! Enforce with linter.
• Use object-oriented interfaces for stateful stuff, and avoid singletons (e.g. our current store/auth design and discussions about moving towards a Client interface)
• Aim to express as much style in linter/formatter config as possible, not in rules we have to remember. Not everything can be covered with the linter, but we should try to cover as much as we can.
• Use pre-commit/prek to run those checks only if they're fast -- mypy for example shouldn't be run in pre-commit/prek
• Run all checks in CI

Other

• Define a clear audience for the changelog so we all agree on what goes in there (i.e. what is valuable signal, and what is noise). IMO, changelog is for users only. Contributors have PRs on GitHub and the Git history. IMO, include only features and bugfixes (i.e. exclude maintenance like version bumps, tooling changes, etc.; documentation changes; etc) (Who is the changelog for? #949)
• Consistency is approximately the most important thing (yes, I know I said this about readability too 😉 I put this in "other" because it applies to docs and code and all other forms of communication)

[Sherwin-14]

For what it's worth, there are some documentation style guides from Matplotlib and Scipy which we could use a reference. I do agree with Matt's comments wholeheartedly though.