tildefriends/docs/guidelines/documentation-guidelines.md

76 lines
2.9 KiB
Markdown
Raw Normal View History

2024-05-11 13:47:14 -04:00
# Documentation guidelines
This document defines the rules used to write documentation in order to make it more consistent.
This documentation is a living document and so are it's rules; you are free to propose changes but in the meantime, please stick to them.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119/).
## File naming
Files SHOULD be named using [kebab-case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/#kebab-case).
Their names should be meaningful and SHOULD not conflict with other files in other directories:
> Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
## Documentation
When writing documentation, the author should have in mind it's target audience: people with varying technical skills and backgrounds, fluency in peer-to-peer-specific terms and mental ability.
The documentation should therefore be acessible and usefule to most people interested in building, using and contributing to Tilde Friends.
2024-05-11 13:47:14 -04:00
### Terminology
`Tilde Friends` refers to the projectas a whole. This can be abbreviated to `TF`.
`tildefriends` refers to the program.
### Style guide
2024-05-11 15:22:25 -04:00
1. Lines SHOULD NOT be wrapped, to allow clients to dynamically wrap them however they want:
```text
This is not very pleasant to read because
the text
is manually wrapped, but the size of the
screen is
smaller than the size the text is wrapped
at. I
need to write even more useless text here
so I get
my point across. Also hi! If you're here
that
means you're either going to contribute to
Tilde
Friends, or that you're reviewing my
stupid
changes. Either way, you're awesome!
```
You MAY use one line per sentence.
2024-05-11 15:22:25 -04:00
2024-05-12 05:20:09 -04:00
2. Lines ending with an `inline code block` or hyperlinks SHOULD NOT end with a period to make copy-pasting easier.
2024-05-11 15:22:25 -04:00
2024-05-12 04:59:26 -04:00
> Example: To build in docker, `$ docker build .`
2024-05-11 15:22:25 -04:00
2024-05-12 04:59:26 -04:00
NB: this does not apply to file names or other text that are not meant to be copy-pasted.
2024-05-11 15:22:25 -04:00
2024-05-12 04:59:26 -04:00
> Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
2024-05-11 15:22:25 -04:00
2024-05-12 04:57:39 -04:00
3. Commands SHOULD start with a caret: (is that the tehnical term ?)
- `$` if the command should be run as the current user
- `#` if the command should be run as root
> Example: To build in docker, `$ docker build .`
2024-05-11 15:22:25 -04:00
More TODO
2024-05-11 13:47:14 -04:00
## License
As per the rest of the code in this repository, the documentation is shared under the [MIT](https://opensource.org/licenses/MIT/) license.
2024-05-12 05:20:09 -04:00
## Changelog
### v1 (2024-05-12)
First version; 3 new guidelines.