generated from ubvu/handbook-template
-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy patheditors-guide.qmd
122 lines (77 loc) · 6.28 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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
---
title: "Editor's guide"
---
Welcome to the Editor's guide to the Handbook! This page contains resources around how the editors work.
The current editors are:
* Chris Hartgerink
* Elisa Rodenburg
* Jolien Scholten
* Tycho Hofstra
* Peter Vos
They can be pinged on GitHub as a team by using `@ubvu/editors` as the tag.
## What does an editor do?
Editors tie together all the strings in this VU Amsterdam 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. Editors also help keep the content relevant to the entirety of VU Amsterdam (faculty specific information is not within scope).
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:
* Writing must be primarily in active voice, both for consistent and engaging text across all pages
* 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.
* Pull requests may not be merged if the QA automations fail
* Links must be `https://`
* 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")
* Where possible, pages with a DOI must link through the DOI (for example, `https://doi.org/10.4444/xxxx` instead of the direct link `https://nature.com/...`)
We try to automate most of these rules, but this is not always possible or accurate enough.
### Topics
For topics we maintain an additional set of standards:
* Topics must be nouns or noun phrases
* Topics are self-contained and aim for brevity
* 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 (for example, "how do I preserve data?")
## 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. -->
## Protocols
### Hackathon protocol
We sometimes run hackathons to create space to contribute. We run hackathons as follows:
Preparation:
* Hackathons are two hours long
* Hackathons are run using Zoom
* Each hackathon has a theme (it helps focus people's energy on something and can inspire participation)
* We use a collaborative note taking document that requires no logging in, which is the central place to navigate the hackathon
* Assign a host
During:
* Open 10 breakout rooms in zoom, allowing participants to freely move around
* The host...
* ...Welcomes everyone with an icebreaker question
* ...Shares the link to the note taking document when people join
* ...Sets the stage for the hackathon when it starts
* ...Announces a break at the halfway mark
* Keep track of all the issues and pull requests opened for the speed blog
After:
* Finish up the speed blog for the hackathon within one week of the hackathon. It does not have to be perfect and is primarily to document that the hackathon happened and some of the things that were done.