Comprehensive, precise, and up-to-date documentation is at the very core of our activity. It helps us to collaborate with each other, and it helps our customers as well. At VSHN we’ve an extensive documentation strategy, and this section of the handbook explains it in detail.

Tools We Use

There are various tools we use to document our work.

Documentation as Code

We extensively make use of Antora and AsciiDoc. This allows us to store documentation in Git, leveraging all the possibilities it gives us (history, pull/merge requests, automated deployments). All (most) Antora based sites are linked in the knowledge base.

To find the source of a documentation simply click on Edit this Page top-right and it will bring you to the source. The README of the documentation sources have more information about how to work with them.


The VSHN Handbook is the document you are currently reading. It documents how VSHN works and how we at VSHN work. It’s geared towards new employees, it serves the purpose of telling potential new hires about us. But it’s also a reference for active VSHNeers to read about VSHN whenever needed, to help have a self-informed live at any VSHN-day and to document any changes or improvements.

The handbook doesn’t contain any confidential or customer specific information, and is therefore meant to be public.

Handbook vs Other Documentation

The following table describes the major differences between the Handbook and other types of documentation.

Handbook Wiki


Stable, carefully reviewed changes

Dynamic, a lot of changes and collaboration

Who is it for

For new and prospective hires, for active VSHNeers: eventually for the public

For active VSHNeers, VSHN customers and VSHN partners


yes, via git

yes, via page history

internal content



confidential content



customer specific content




Your first day at VSHN

How you setup your e-mail address

How Team and Interest Groups work

Team shift scheduling table

What the VSHNday is

Meeting notes from the VSHN day

Confluence Wiki

Internal or confidential information is documented in the Atlassian Confluence VSHN wiki.

If you use Firefox you can add the Confluence and Jira search engine to your "One-Click Search Engines" list by clicking the button on the location bar. Then, in about:preferences#search you can assign a keyword to it, for faster searches.

add search engine

You should take a look at our wiki, and if you find a mistake, an error, or a typo, select the "Edit" button (or just hit the E key) and correct it. We use Confluence as wiki software. Don’t worry of making mistakes, Confluence stores the history of every change, and you can always roll back a previous version of any page if needed.

Customer Spaces

Each VSHN customer gets its own Space in our wiki. Access can be granted for the customer users to access their space.

  • Space Name: Customer: <customername>

    • 00-OnCall: Contains relevant information for 24x7 on-call engineers. Exists only, if the customer has a 24x7 support SLA

    • 01 Services: Overview over all services we’re operating for the customer with a tight focus on anything the is customized/different from our standard setups and products

      • <Service A>: Managed GitLab

      • <Platform B>

        • DB Servers

        • Load balancers

        • Monitoring checks

    • 02 Meeting notes:

      • <2019–05–10 Meeting bla blah blah> (use meeting notes template!)

    • 03 HowTo articles: No further structure, just single pages per how-to article, use tags!

    • 12 Projects: Running projects (done or closed projects are archived and relevant information moved to How-to articles and Services

    • 13 Incident reports:

      • <2019–05–10 xyz incident postmortem>

Interest Groups

Each VSHN Interest Group gets it’s own wiki space. There is no given structure, do whatever works for you.

  • Space Name: VSHN <Interst Group name> Interest Group

  • Space Key: V< 2 chars of group name>IG


Each VSHN team gets it’s own wiki space. There is no given structure, do whatever works for you.

  • Space Name: VSHN <Teamname> Team

  • Space Key: V<first 2 chars of Interest Groupname>Q


As soon something has value for not only the Team, it must be documented in a "global" Wiki space (or maybe the handbook).

Some examples on what’s a good and a bad idea to keep inside the team space:


  • How this particular Team works, how to work together

  • Team shift planning tables and stuff like that

  • Team internal organization (projects)

  • Meeting notes (name them <year>-<month>-<day> …​)

  • Retro notes (name them <year>-<month>-<day> …​)


  • How-tos that also have value for other teams (for example, a technical guide on how to setup something)

  • Workflows that also affect other teams (for example, how we hand over tickets to another team, etc.)


Finance, PeopleOps, monthly invoice controlling, etc.

  • Space Name: VSHN Backoffice

  • Space Key: VBO


Contains short lived or frequently updated organizational stuff that doesn’t fit into the Handbook, for example, Meeting notes, current projects, how-to articles

  • Space Name: VSHN Business

    • 02 Meetings (Meeting notes)

    • 03 How-to articles (should mostly go into Handbook)

    • 12 Projects (non tech projects, for example, "New Documentation structure")

    • 13 Research

  • Space Key: VINT


Contains short lived or frequently updated organizational stuff that doesn’t fit into the Handbook, for example, Meeting notes, current projects, how-to articles, maintenance logs, Research, etc.

  • Space Name: VSHN Technical

    • 03 How-to articles

    • 12 Projects (non customer specific tech projects)

    • 13 Research

    • Maintenance Logs

  • Space Key: VT

Git & GitLab

Code (Apps, Tools, Ansible playbooks and roles, Puppet profiles and modules, etc.) are documented within the same git project, usually in a README written in Markdown or Asciidoc.


Our ticket system is based on Atlassian Jira. There is a whole page in this handbook on How we use Jira.

Regarding documentation it’s important to say that we document everything related to a specific task, problem or incident directly in the ticket but link related tickets, wiki pages, etc. to the ticket.

For incidents, usually a incident report is is written in the wiki based on the information in the ticket gathered during debugging an analysis.