Milestone discussion: kubernetes#90 (closed)

We've engineered so much knowledge and technology in the past couple of months. Now that we have a minimum viable product, I'd like we take some time to add documentation in a smart way.

Documentation should be considered business code: The less the better; the more mature tools we borrow from external sources, the better. Documentation must be maintained. We need adapt our procedure to force the update of documentation when the implementation is updated.

Pitfalls

AGEPoly is a very dynamic organization. Lack of definite code owners entails a higher cost for technical complexity since new managers/officers must be onboarded and learn to seek help; this is exacerbated by their potential lack of experience. Since it is unrealistic to bound technical complexity, it must be abstracted and justified. Therefore, documentation should not contain personal opinions, but rather reference external resources (such as recognizable blog posts, software development guidelines and official documentation). Every argument must be backed by a corresponding reference. Wikipedia articles are the bare acceptable minimum.

Documentation categories

Four main documentation categories are considered:

Architecture

• Bird's eye (Audience: AGEPoly's CDD)
  Documents giving a general overview of all our technological stack. These documents should contain:

  • A one page flowchart of all services provided by AGEPoly (issue TBD)
  • A one page diagram of the technology stack used by AGEPoly (issue TBD). In particular, is should present the relationship between Debian, Proxmox, Ansible, Kubernetes, Traefik.
  • A one page diagram of our hardware stack (issue TBD)
  • A one page flowchart of the network stack (issue TBD)
  • A one page diagram of the provisioned security stack (issue TBD)

• Technical decisions and policies (Audience: AGEPoly's IT manager, average IT aficionado)
  Documents detailing technology stack components. In particular they should clearly explain their advantages, disadvantages, costs, consequences and possible pitfalls in a manager-friendly language. This should contain:

  • A chapter per diagram/flowchart detailed in the bird's eye. A section per component in said diagram/flowchart.

Design

• Design decisions detailing the scope of each technology. In particular, this should contain:

  • Clear limitations on what a given technology is used for. For example, ansible is used for infrastructure provisioning and maintenance; This document should make clear that services provisioned by Kubernetes are not part of said infrastructure, but the databases provided to Kubernetes are.

• Decisions detailing how we use each technology. For example, Kubernetes-provisioned service configurations are automatically generated from a simple service description.

Audience: CS student

Implementation

• Description of all of AGEPoly projects and how/which product they relate to.

• Description of design decisions for each project. For example, Silhouette is used to generate Kubernetes service configurations; It is written in haskell because of its strong type system and convenient language features such as pattern matching and algebraic data types, which allows writing policies in a declarative style while being guaranteed by a compiler.

Audience: CS student

Procedures

• Document how to consume, as an external user each of AGEPoly products.

• Document how to add, document, maintain, deprecate and remove features from each project (feature lifecycle, issue templates, merge request templates).

Audience: CS student

Transversal

• Documentation must written in Commonmark Markdown when possible, or Pandoc Markdown when necessary.
• Documentation must be written in English. It must be spell-checked. You may use Hunspell to spell check the text.

You can verify a word usage, context and frequency in the Corpus of Contemporary American English website. The use of words with frequency above 1000 is strongly recommended.