forked from cory/tildefriends
76 lines
2.9 KiB
Markdown
76 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
### Terminology
|
|
|
|
`Tilde Friends` refers to the projectas a whole. This can be abbreviated to `TF`.
|
|
|
|
`tildefriends` refers to the program.
|
|
|
|
### Style guide
|
|
|
|
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.
|
|
|
|
2. Lines ending with an `inline code block` or hyperlinks SHOULD NOT end with a period to make copy-pasting easier.
|
|
|
|
> Example: To build in docker, `$ docker build .`
|
|
|
|
NB: this does not apply to file names or other text that are not meant to be copy-pasted.
|
|
|
|
> 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`.
|
|
|
|
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 .`
|
|
|
|
More TODO
|
|
|
|
## License
|
|
|
|
As per the rest of the code in this repository, the documentation is shared under the [MIT](https://opensource.org/licenses/MIT/) license.
|
|
|
|
## Changelog
|
|
|
|
### v1 (2024-05-12)
|
|
|
|
First version; 3 new guidelines.
|