Research Support Handbook

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:

They can be pinged on GitHub as a team by using @ubvu/editors as the tag.

Tip

For the handbook’s technical details, we have a separate page!

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.

Editors also are responsible for managing time-sensitive merging of Pull Requests on GitHub. Sometimes, we know things have to change on a specific date. To do this, we can schedule PR merges by adding the relevant date in the opening comment of the Pull Request (example; editors can edit comments):

/schedule YYYY-MM-DD

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 Research Support Handbook are made via pull requests. Each change needs approval from at least one editor.
    • 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)
  • 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?”)

Tools

For tools we maintain the following standards:

  • Tools must be supported in some way by VU Amsterdam, either full support such as for Research Drive or SciStor, or at least some consultancy, such as for SURF tools like Snellius or Research Cloud.
  • Each tool description consists of at least the pages: What is …?, Costs and Getting Access, Support and Contact, Quick Start.
  • A tool section can contain an additional Documentation section for “How to’s” and manuals that help researchers accomplish specific tasks with the tool. The structure of the Documentation section is necessarily more free form. To help navigation, additional subsections can be made under Documentation.
  • The pages in tools always show the date of the last commit to the page, to show researchers the manuals are actively kept up to date.
  • Tool pages will be checked and if necessary revised at least twice a year at the Handbook Hackathons.

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.

We create Milestones for upcoming Hackathons. This allows us to prioritise issues by assigning them to a milestone, indicating that we want to work on the issue at or before that Hackathon.

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, tool pages 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.

Protocols

Weekly co-working

Each week we have an online co-working hour, attended by the editors. This is a time to discuss issues, pull requests and other relevant matters or just work on the Research Support Handbook. Other contributors are free to join as well.

Hackathon protocol

We run hackathons twice a year to create space to contribute. We run hackathons as follows:

Preparation:

  • Hackathons are at least half a day long

  • Hackathons are always live

  • Each hackathon has a theme (it helps focus people’s energy on something and can inspire participation)

  • 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.

Troubleshooting

There are some common mistakes that can happen. We keep track of some of the quirks we observed to help you troubleshoot independently:

  • Is the filename .qmd exactly?
  • Is the relative path from topic -> topic ../topics/name.qmd?

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.↩︎