Ebury Knowledge Transfer - Technical Documentation Guidelines

As stated in the Ebury Knowledge Transfer blueprint, the technical documentation should be structured around its four different functions: tutorials, how-to guides, technical references and discussions. Each of them requires a distinct mode of writing that we can adapt to Ebury’s needs.

They must live in code, specifically in /docs folder of each repository, so that they can be automatically discovered by GitHub Pages and easily transferred to any other preferred tool. The index.md file will be used as the landing page for the documentation.

Initially, templates will be provided in markdown (.md) files and they will be extended for the usage of MkDocs for further automation.

Tutorial Template

Learning-oriented / Practical knowledge / Most useful when studying

They are lessons your project needs in order to show a beginner that they can achieve something with them. It should be focused on a learning objective and take the reader by the hand through a series of steps to complete a project of some kind.

Technical Documentation - Tutorial Template

General Guidelines

  • It should be the starting point to get started.
  • It must be repeatable.
  • Every step in the tutorial has to result in a small success for the reader.
  • It needs to be concrete, and avoid abstractions.
  • Explanations are not important when somebody is learning a new skill, what they need to learn is how to do something.
  • It should avoid disruptions with content like options or alternatives.

Examples

How-To Template

Recipes-oriented / Practical knowledge /Most useful when coding

Think about them as “recipes” to guide the reader through the steps involved in addressing key problems and use cases. They mainly answer “How do I….?” types of questions.

They are more advanced than tutorials. In case further knowledge is required, you might need to consider writing tutorials or references for that specific topic to support your how-to guidelines.

Technical Documentation - How-To Template

General Guidelines

  • It needs to include a series of steps to be followed in order.
  • In case of prerequisites, they must be included before the real starting point.
  • It needs to be focused on a specific goal.
  • It should address a specific question.
  • It should avoid unnecessary explanations (with some flexibility, you can assume the reader has some knowledge of the topic).
  • It should provide practical usability.

Examples

References Template

Information-oriented / Theoretical knowledge / Most useful when coding

They should address the technical aspects of a specific topic. They describe how it works and how to use it but assume that the reader has a basic understanding of key concepts.

Technical Documentation - References Template

General Guidelines

  • It should provide the reader with facts.
  • It should have the same structure as the code base.
  • The content should be as clear as possible, avoiding assumptions or discussions.
  • The information must be accurate.

Examples

Discussions Template

Understanding-oriented / Theoretical knowledge / Most useful when studying

They are explanations or discussions to clarify a particular topic at a high level.

The RFC is the perfect example of this kind of documentation. They live in the ebury-blueprint repository, and it exists a live version of Blueprints at http://blueprints.ebury.rocks/.

Technical Documentation - Discussions Template

General Guidelines

  • It should focus on explanations to clarify a particular topic.
  • It should provide background and context.
  • It should explain why it’s required.
  • It should provide multiple examples and consider alternative approaches.
  • It should have connections with any other relevant areas.
  • It’s not required to provide in-depth instructions or technical details.

Examples

References