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.

Tools We Use

There are various tools we use to document our work.

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 Other Documentation

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

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 Squad and Chapters work

Squad 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

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 24/7 OnCall technicians. Exists only, if the customer has a 24/7 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>

Chapters

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

  • Space Name: VSHN <Chaptername> Chapter

  • Space Key: V<first 2 chars of chaptername>C

Rules

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

Squads

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

  • Space Name: VSHN <Squadname> Squad

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

Rules

As soon something has value for not only the Squad, 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 squad space:

Good:

  • How this particular Squad works, how to work together

  • Squad shift planning tables and stuff like that

  • Squad 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 squads (for example, a technical guide on how to setup something)

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

Backoffice

Finance, human resources, monthly invoice controlling, etc.

  • Space Name: VSHN Backoffice

  • Space Key: VBO

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

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.

Jira

Our ticket system is based on Atlassian Jira. There is a whole chapter 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.