generated from ubvu/handbook-template
-
Notifications
You must be signed in to change notification settings - Fork 6
/
editors-guide.qmd
85 lines (51 loc) · 4.52 KB
/
editors-guide.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
---
title: "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:
* Chris Hartgerink
* Elisa Rodenburg
* Jessica Hrudey
* Jolien Scholten
* Lena Karvovskaya
## 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.
[^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.
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](https://capitalizemytitle.com/style/APA/))
* 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:
* [Topics](https://github.com/orgs/ubvu/projects/7/views/1)
* [Guides](https://github.com/orgs/ubvu/projects/7/views/2)
## 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.
<!-- ### Deleting branches
After merging Pull Requests, it is expected to clean up the branch by deleting it. We enable auto deletion upon merging, but if that for some reason does not happen, please go ahead and "Delete branch". We may periodically clean up branches in the repository. -->
<!-- ### Closing pull requests
Not all pull requests make it into the handbook, and that is okay. We want to ensure that pull requests are not closed at random, and provide some norms around doing so.
Stale pull requests can be closed with a note for the contributor that they are welcome to request the pull request to be re-opened. We automatically mark pull requests as stale after 30 days.
Pull requests that provide too much discussion and do not have a pathway to resolution may be closed for being disputed. This does not mean the content goes to waste – here we recommend an issue to be opened to continue the discussion. Please note that disputed topics can only be carried on if done so in a mutually constructive manner. -->