Documentation

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.

Documentation Index

Documentation Content Audience

Company Handbook

The VSHN Company Handbook

VSHNeer

Product Documentation

VSHN Product Documentation

VSHNeer, Prospect, End-User

Confluence Wiki

Company Wiki

VSHNeer, (End-User)

Knowledgebase

Technical Knowledgebase

Technical VSHNeer

APPUiO docs

APPUiO End-User

Technical VSHNeer, End-User

APPUiO Portal docs

APPUiO Portal End-User

VSHNeer, End-User

AppCat docs

VSHN Application Catalog End-User

Technical VSHNeer, End-User

VSHN Portal docs

VSHN Portal End-User

VSHNeer, End-User

Project Syn

Project Syn

VSHNeer, End-User, Prospect

K8up

K8up (Kubernetes Backup Operator)

VSHNeer, End-User, Prospect

Company Website

Mostly marketing and blog articles

Prospect

Audience

Documentation is only as good if the content matches the audience reading it. We see the following audiences:

VSHNeer

All VSHNeers.

Technical VSHNeer

VSHNeer doing system administration, solution architecture and other technically focused jobs.

End-User

A person actively using VSHN products day-to-day.

Prospect

A potential customers.

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.

Handbook

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 Wiki

The following table describes the major differences between the Handbook and our Wiki.

Handbook Wiki

Stability

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

History

yes, via git

yes, via page history

internal content

no

yes

confidential content

no

yes

customer specific content

no

yes

Examples

Your first day at VSHN

How you setup your vshn.ch e-mail address

How Team and Interest Groups work

Team shift scheduling table

What the VSHN Connect 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.

Account

VSHNeers must login with their @vshn.net Address and are automatically logged in via our IdP.

Customers can be added as guests and assigned to their respective spaces. Customers are required to use their personal Atlassian accounts to access our wiki.

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>

Work Groups

Each VSHN Work Group gets its own wiki space. There is no given structure, do whatever works for you.

  • Space Name: VSHN <Work Group name> Work Group

Teams

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

  • Space Name: VSHN <Teamname> Team

Rules

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:

Good

  • 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> …​)

Bad

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

Business

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

Technical

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

GitHub & 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.

These projects can also contain an Antora-based documentation under docs/ which is published under a specific domain. For example Commodore components do have their documentation in the docs/ folder and the documentation is available in the Component Hub.

Jira

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 an incident report is written in the wiki based on the information in the ticket gathered during debugging an analysis.