<commit_before># Contributing Documentation in SnabbSwitch

## README.md, README.md.src and README(.inc)

The SnabbSwitch documentation is organized in README's spread across the
code base. If you commit changes you should look for the "nearest" README
file related to the modules you changed and update these. There are three
different kinds of README files:

* `README.md` — A portion of the SnabbSwitch manual, embedded by GitHub
  too. These are often (but not always) artifacts built from a `.src`
  file. Edit these if no `.src` is available (see below).
* `README.md.src` — A build recipe. If available, this is the one you
  must edit. These are formatted in [GitHub Flavored
  Markdown](https://help.github.com/articles/github-flavored-markdown/).
* `README(.inc)` — Plain text files included as the `--help` message of
  SnabbSwitch programs. These should be using only the ASCII character
  set to ensure compatibility with older terminals.

For instance if you had changed the API of `lib.protocol.ethernet` you'd
need to update the documentation in `lib/protocol/README.md.src`. It is
important that you use the correct header level (e.g. `##`, `###`,
...). Which level you are at can be seen in `doc/genbook.sh` (see
*Building A Standalone Documentation*).

Be sure to know who your target audience is. We recognize three different
groups:

* **Casual users:** Some programs are targeting *anyone* using Snabb
  Switch, make sure that their `--help` message (`README.inc`) does not
  require prior knowledge.
* **Power users:** Public APIs like `core.packet` or
  `lib.protocol.ethernet` are there for app designers to use. These
  should be well documented but may require knowledge of Lua and other
  parts of the Snabb Switch system.
* **Contributors:** Some documents (like the one you are reading now) are
  facing towards Snabb Switch contributors. They can be frequently
  updating and even contain open questions. We should ensure that these
  always reflect the current state of affairs.

### Building README.md Files

In order to recreate a `README.md` file from its `.src` you need to
`make` it. E.g. in case of our example above you would run:

```
make lib/protocol/README.md
```

You need to commit the resulting `README.md` (and possibly generated
diagram images, see *Including Diagrams*) alongside the updated
`README.md.src`.

### Including Diagrams

The main reason for the `README.md.src` to `README.md` step is that we
use a custom Markdown pre-processor to be able to embed ASCII diagrams in
our documentation. These ASCII diagrams will be rendered to pretty images
by [ditaa](http://ditaa.sourceforge.net/). In order to build `README.md`
files containing diagrams you will need a local installation of ditaa.<commit_msg>documentation-guide: Update according to #743.<commit_after># Contributing Documentation in SnabbSwitch

## README.md, README.src.md and README(.inc)

The SnabbSwitch documentation is organized in README's spread across the
code base. If you commit changes you should look for the "nearest" README
file related to the modules you changed and update these. There are three
different kinds of README files:

* `README.md` — A portion of the SnabbSwitch manual, embedded by GitHub
  too. These are often (but not always) artifacts built from a `.src`
  file. Edit these if no `.src` is available (see below).
* `README.src.md` — A build recipe. If available, this is the one you
  must edit. These are formatted in [GitHub Flavored
  Markdown](https://help.github.com/articles/github-flavored-markdown/).
* `README(.inc)` — Plain text files included as the `--help` message of
  SnabbSwitch programs. These should be using only the ASCII character
  set to ensure compatibility with older terminals.

For instance if you had changed the API of `lib.protocol.ethernet` you'd
need to update the documentation in `lib/protocol/README.src.md`. It is
important that you use the correct header level (e.g. `##`, `###`,
...). Which level you are at can be seen in `doc/genbook.sh` (see
*Building A Standalone Documentation*).

Be sure to know who your target audience is. We recognize three different
groups:

* **Casual users:** Some programs are targeting *anyone* using Snabb
  Switch, make sure that their `--help` message (`README.inc`) does not
  require prior knowledge.
* **Power users:** Public APIs like `core.packet` or
  `lib.protocol.ethernet` are there for app designers to use. These
  should be well documented but may require knowledge of Lua and other
  parts of the Snabb Switch system.
* **Contributors:** Some documents (like the one you are reading now) are
  facing towards Snabb Switch contributors. They can be frequently
  updating and even contain open questions. We should ensure that these
  always reflect the current state of affairs. This also includes
  implementation details which should be documented as source code comments.

### Building README.md Files

In order to recreate a `README.md` file from its `.src` you need to
`make` it. E.g. in case of our example above you would run:

```
make lib/protocol/README.md
```

You need to commit the resulting `README.md` (and possibly generated
diagram images, see *Including Diagrams*) alongside the updated
`README.src.md`.

### Including Diagrams

The main reason for the `README.src.md` to `README.md` step is that we
use a custom Markdown pre-processor to be able to embed ASCII diagrams in
our documentation. These ASCII diagrams will be rendered to pretty images
by [ditaa](http://ditaa.sourceforge.net/). In order to build `README.md`
files containing diagrams you will need a local installation of ditaa.
{'fraction_non_alphanumeric': 0.08133971291866028, 'fraction_numerical': 0.000531632110579479, 'mean_word_length': 4.230769230769231, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4799047', 'n_tokens_mistral': 1616, 'n_tokens_neox': 1536, 'n_words': 794}