Editor’s guide

Welcome to the Editor’s guide to the Handbook! This page contains resources around how the editors work.

Temporary initial editors are:

What does an editor do?

Editors tie together all the strings in this community handbook. We keep a bird’s eye view to ensure that what you read makes sense. Editors also help ensure the style and quality of the different pages are similar.

Each editor commits themselves to providing timely reviews of topics, guides, or both.1 This commitment is for a limited time and can be renewed. We also welcome more editors at any time, given that we do not expect all editors to review everything.

As we go on this journey together, we may assign more specific responsibilities as they emerge.

Quality standards

As editors, we maintain a bunch of quality standards, both automated and not automated. If you are reading this as a contributor, you will greatly help us out by taking these into account.

Here are some quality standards we maintain throughout the handbook:

  • Acronyms must be written in full at least once on the page where they are used
  • All changes to the handbook are made via pull requests. Each change needs approval from two editors.
  • All images must have alt text
  • Links must be descriptive (no “click here” links)
  • No writing in name of the handbook (for example, “we recommend repository X”)

Topics

For topics we maintain an additional set of standards:

  • Topics must be nouns or noun phrases
  • All topics must be title capitalized (see also the helpful tool CapitalizeMyTitle.com)
  • No include statements are allowed in topics
    • Include statements must be prefaced with the relevant section heading, as the title of a topic is not reproduced.
  • No use of special Quarto code is allowed. Only use regular markdown in topics.

Guides

For guides we maintain other standards:

  • Guides must be phrased as questions that the reader will get answers to

How to keep an overview of everything?

With so many issues and pull requests, it is easy to get lost as an editor. We have a project management board that can be helpful identifying what is going on at this time:

Etiquette

As editors, we may have to make tough calls at times. It is important for us to make people feel welcome and appreciated, even if their contribution is not immediately included. That being said, we reciprocate the consideration given to us. We operate under a generosity policy, and if reciprocated, we stay generous.

GitHub etiquette

As editors, we also maintain a certain GitHub etiquette. It is necessary to make managing a project with so many moving pieces and contributors. Important is:

  1. New topics or guides must be linked to the issue proposing it
  2. Each pull request should have a clear purpose and stick to it (for example, no editing a guide when proposing a topic)

Item 2 also means changes should be branch specific, as pull requests are based off branches. It makes it much harder to review things if there are many different kinds of changes, as we editors will need to keep track of all of this.

Simplicity is our friend. Simplicity helps us from making mistakes.

Footnotes

  1. Each editor chooses which of these they want to focus on. Editors get auto-invited to review the changes. Timely means within a week.↩︎