210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
# Documentation Principles
|
||
|
||
## Scope
|
||
This document aims to:
|
||
- Define the value and importance of documentation for the protocol and in the ecosystem
|
||
- Define key terms
|
||
- Describe the principles of Documentation processes
|
||
- Describe the various types of Documentation
|
||
|
||
## Concepts
|
||
We strongly believe in documentation, not because of the documentation itself, but because of what it represents, the
|
||
values it upholds and a possibly near universal recognition of worth for the knowledge it contains.
|
||
|
||
The rest of this document will describe those in details.
|
||
|
||
### Proof of Work
|
||
The expression ***Proof of Work***, shortened to ***PoW***, will be used throughout this document to represent the effort
|
||
made by someone to articulate and communicate meaningfully about relevant matters towards others. It comes from the
|
||
[Proof-of-work system](https://en.wikipedia.org/wiki/Proof-of-work_system).
|
||
|
||
There is no restriction on the amount of work itself, which can range from near-to-nothing to extensive amounts of time
|
||
and money. It will directly depend on the situation and the goal of the debate.
|
||
|
||
Anyone in the community (including from the boards) who wants to participate in a debate MUST produce ***PoW***.
|
||
***PoW*** does not mean minimal amount of knowledge. Rather, ***PoW*** means minimal amount of effort.
|
||
We expect back-and-forth argumentation backed by ***PoW*** as people participate in an exchange of some sort, until no
|
||
more argumentation can be brought up, which will settle that particular exchange.
|
||
|
||
### Documentation
|
||
The word ***Documentation*** will be used as a generic concept throughout this document.
|
||
Any document that seeks to be recognized as *Documentation* must incorporate at least one ***PoW***.
|
||
|
||
It is defined as something that:
|
||
- Is available publicly
|
||
- Is directly reachable using a [URL](https://en.wikipedia.org/wiki/URL)
|
||
- Is a standalone piece of work, or directly incorporated in one at the same location
|
||
- Is written in English if text-based
|
||
- Incorporates at least one ***PoW*** from the concepts below
|
||
- Can be re-used by others to build on
|
||
- Provides a publicly accessible channel for feedback
|
||
|
||
Examples of Documentation:
|
||
- A standalone HTML page
|
||
- A PDF document
|
||
- An [ODT](https://en.wikipedia.org/wiki/OpenDocument) document
|
||
- A Gogs/Gitea/Github/Gitlab issue
|
||
- A comment on an issue
|
||
- A Cryptpad document
|
||
- A Google Docs document
|
||
- A schematic wireframe
|
||
- A fully rendered and styled visual mockup of a GUI
|
||
|
||
Any produced *Documentation* is guaranteed to be reviewed by the governing body in a timely fashion. *Documentation* will
|
||
therefore become the ideological currency of the project and ensure everyone who worked to produce one will be able to
|
||
"trade" it for something else (e.g. trade it for the review of the documentation).
|
||
|
||
We make no generic requirements on the format, length or overall wording of *Documentation*, as long as the vast majority
|
||
of the community is happy about it. This is on purpose, following on the issues met so far using a too strict proposal
|
||
process and we’ll rely on a naturally occurring balance with gentle nudges in the right direction.
|
||
|
||
The Technical Board will produce a list of officially recommended formats, way of sharing and provide sample templates
|
||
for the various fitting use case so people can easily get started. Those will be kept up to date and relevant.
|
||
|
||
### Implementation
|
||
The term ***Implementation*** will refer to the deliverable or the actual product derived from a given *Documentation*.
|
||
It is a generic term, it's meaning will change depending on the role/occupation of the deliverer.
|
||
|
||
Examples of Implementation:
|
||
- As a software developer: source code
|
||
- As a graphic designer: Wireframes and mockups
|
||
- As a User Experience engineer: Guidelines/recommendations
|
||
- As a system administrator: Install guides, deployment scripts, etc.
|
||
|
||
## High-level concepts
|
||
To ensure successful *Documentation*, it is essential to respect some core concepts that reflect the value of the protocol,
|
||
its openness and the recognition of ***PoW***.
|
||
|
||
The following concepts are how something will be judged as qualifying as a ***PoW***.
|
||
|
||
### Extract, organize and materialize thoughts
|
||
Our experience shows that the human mind tends to underestimate risks, difficulty level and overall workload.
|
||
Therefore we believe that the act of writing the *Documentation* - regardless how small - simply forces one to think further
|
||
and in more details about what one tries to accomplish and filters the most basic and unconscious biases.
|
||
|
||
### State functional problem to be solved
|
||
While chat or voice exchanges are good for quick exchanges, it’s easy to lose sight of the actual problem one is trying
|
||
to solve and the involved scope, or simply not really know what problem is currently be solved. By stating up front the
|
||
problem, the scope is set and can be enforced in further exchanges.
|
||
|
||
### Facts backing
|
||
**This is *Proof of Work***
|
||
|
||
As this is a technical exercise, it is important that any statement that influences choices, like "it is very likely that
|
||
X happens", be backed up by objective, quantifiable and/or qualifiable facts from an independent source.
|
||
|
||
### Usage feedback and usability
|
||
**This is *Proof of Work***
|
||
|
||
Using or testing software/*Documentation* or any kind of item that comes from a ***PoW*** becomes itself a ***PoW*** once
|
||
that experience is documented.
|
||
|
||
This is typically:
|
||
- Software tests in development cycle
|
||
- Daily usage from end-users
|
||
- Bug reports of software of the protocol specification itself
|
||
- Feature request from end-users
|
||
|
||
In addition to load testing, pen-testing, etc, usability focus groups (whether remote or in person), feedback via surveys
|
||
and suggestion forms provide an excellent opportunity to gain new and sometimes unexpected insights. If the same
|
||
feature request or complaint appears frequently, it should be considered actionable. Putting together such a compiled
|
||
list or results of testing provides actionable next steps.
|
||
|
||
Ad hoc observations such as “my group found this feature difficult to use” can be logged as an issue and may also be
|
||
considered; however compiling quantitative evidence (X% of users could not complete an assigned task) is strongly encouraged.
|
||
|
||
UX professionals and designers should also be encouraged to submit wireframes, mockups, and process documentation
|
||
for future functionality. (Not just "what’s broken?" but "what can be dreamed and built?").
|
||
In this instance, a well-developed use case is considered ***PoW***.
|
||
|
||
### Sources linking
|
||
**This is a *Proof of Work***.
|
||
|
||
As facts must come from external sources, it is critical to include links to those sources, so anyone evaluating the
|
||
document can have access to the same information as the author without having to research the data themselves.
|
||
|
||
### Proposed solution
|
||
**This is a *Proof of Work***.
|
||
|
||
Once the problem to be solved and the scope are documented, one will describe the proposed solution that solves the
|
||
stated problem/issue.
|
||
Next to the description of the solution, one MUST reiterate in a short conclusion how the solution effectively solves
|
||
the problem.
|
||
|
||
### Rationalisation
|
||
**This is a *Proof of Work***.
|
||
|
||
As one goes through the proposed solution, one will use the various facts and/or linked sources to justify the proposed
|
||
solution. One CANNOT rely on common knowledge, as this is a cognitive bias. On the other hand, one is free to rely on
|
||
required knowledge.
|
||
|
||
Example: If describing an HTTP endpoint, one may have to justify the validity of the HTTP choices made (POST vs PUT, etc.),
|
||
but one will not have to justify TCP principles.
|
||
|
||
### Implementation
|
||
**This is a *Proof of Work***.
|
||
|
||
This validates the proposed solution with an actual Implementation and ensures that the theoretical outcome is feasible
|
||
in practice, as a real product for real users.
|
||
|
||
### Peer convincing
|
||
**This is a *Proof of Work***.
|
||
|
||
Proposals should be written in a way that one attempts to convince others that the proposed solution is the correct one,
|
||
instead leaving the fact checking work to their reviewing peers.
|
||
One MUST NOT assume they are correct to start with. They MUST convince others of the validity of their claims using the
|
||
elements described above.
|
||
It MUST be easier to read the proposal than to write it.
|
||
|
||
## Types
|
||
*Documentation* will be divided into several types, each having their own requirements and goals.
|
||
Except for The Protocol Specification, any of those *Documentation* can be put forward by the governing body or by the
|
||
community.
|
||
|
||
Types are not mutually exclusive and a single *Documentation* can be of several types.
|
||
|
||
The various types will outline the various stages/steps of the overall process which is a recurring cycle:
|
||
1. Guides/Recommendations/Templates and The Protocol Specification allow Implementations to be made
|
||
2. Implementations trigger Issues/Bug reports/User feedback
|
||
3. Issues/Bug reports/User feedback trigger Research/Analysis
|
||
4. Research/Analysis inspire Guides/Recommendations/Templates and Proposals
|
||
5. Proposals aim to enhance Guides/Recommendations/Templates and The Protocol Specification - Back to first step.
|
||
|
||
### Issue/Bug report/User feedback
|
||
This kind of *Documentation* will mostly rely on [Usage feedback and usability](#usage-feedback-and-usability).
|
||
|
||
**Example**: Request to clarify recommended setup for synapse (Github issue).
|
||
|
||
### Research/Analysis
|
||
This kind of *Documentation* will mostly rely on [Facts backing](#facts-backing), [Sources linking](#sources-linking) and
|
||
[Peer convincing](#peer-convincing). It can be produced by anyone and will be the primary backing work for other *Documentation*.
|
||
|
||
**Example**:
|
||
|
||
- Notes on privacy and data collection of Matrix.org ([Github Gist](https://gist.github.com/maxidorius/5736fd09c9194b7a6dc03b6b8d7220d0#notes-on-privacy-and-data-collection-of-matrixorg)).
|
||
- Matrix Server ACL addition analysis ([Github gist](https://gist.github.com/maxidor/b25769f1a89c8860b928babe795bbaaf)).
|
||
|
||
### Guide/Recommendation/Template
|
||
This kind of *Documentation* will mostly rely on [Usage feedback and usability](#usage-feedback-and-usability) and
|
||
[Proposed solution](#proposed-solution).
|
||
|
||
**Example**: Matrix stack installation guide ([Github repo](https://github.com/PC-Admin/PC-Admin-s-Synapse-Setup-Guide)).
|
||
|
||
### Proposal
|
||
This kind of *Documentation* will mostly rely on [Proposed solution](#proposed-solution), [Rationalisation](#rationalisation)
|
||
and [Peer convincing](#peer-convincing).
|
||
|
||
**Example**: Matrix client auto-discovery ([Google Docs](https://docs.google.com/document/d/1vF-uWlUYmf1Xo161m871H1upJbwiIPeikWGWzaE_lrU)).
|
||
|
||
### Implementation
|
||
This kind of *Documentation* will mostly rely on [Facts backing](#facts-backing) and [Implementation](#implementation).
|
||
|
||
**Example**: any software implementation following a protocol specification.
|
||
|
||
### The Protocol Specification
|
||
The Protocol Specification will be one of the final products and the most important deliverable for the Governing Body.
|
||
|
||
As a special authoritative document, its main Proof of Work will be "delayed" and mostly contained in its ability of
|
||
[Peer convincing](#peer-convincing) and being backed by two independent [Implementation](#implementation), adding to a
|
||
total of three independent *Documentations* (one is the specification, two are the implementations).
|