From 16e56ad9ca63fbc3e824ed054f09bd56ab1567ea Mon Sep 17 00:00:00 2001 From: Jens Langhammer Date: Sat, 29 Jan 2022 23:37:23 +0100 Subject: [PATCH] website/docs: add rough documentation style guide Signed-off-by: Jens Langhammer --- .../docs/writing-documentation.md | 38 +++++++++++++++++++ website/developer-docs/translation.md | 6 ++- website/sidebarsDev.js | 4 ++ 3 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 website/developer-docs/docs/writing-documentation.md diff --git a/website/developer-docs/docs/writing-documentation.md b/website/developer-docs/docs/writing-documentation.md new file mode 100644 index 000000000..d8baaf80f --- /dev/null +++ b/website/developer-docs/docs/writing-documentation.md @@ -0,0 +1,38 @@ +--- +title: Writing documentation +--- + +Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. Here are a few guidelines to ensure +the documentation is easy to read and uses similar phrasing. + +# General guidelines + +- authentik should always be stylized as `authentik` (with a lower-case a and ending with a k) +- Documentation should use American english +- Feel free to use Docusaurus-specific features, see [here](https://docusaurus.io/docs/next/markdown-features) +- Use abbreviations where it makes sense (for commonly used terms like SAML and OAuth) +- Phrasing should never blame the user, and should be subjective, i.e + + - **DON'T** `You may never click x.` + - **DO** `x should never be clicked.` + +- When referring to other objects in authentik, use cursive text, and link to the corresponding documentation if possible. +- When referring to external tools, give an example how to use the tools or explain how the user can use them. +- Make sure to add the documentation to add to the sidebar, if adding a new page. +- Test how the documentation renders using the Netlify Preview, especially when using Docusaurus-specific features. + +If you find any documentation that doesn't match these guidelines, feel free to either open an Issue or a PR so they can be fixed. + +## Integration guidelines + +These guidelines apply in addition to the ones above. + +- For placeholders, use angle brackets (``). + + Make sure to also define if the placeholder is something the user needs to define, something another system defines, or randomly generated. + + If you're adding configuration snippets to the documentation, and the snippet is in a language that supports comments, + other placeholders may be used, for example comments referencing an earlier step. + +- For placeholder domains, use `authentik.company` and `app-name.company`, where `app-name` is the name of the application you are writing documentation for. +- Try to order the documentation in the order that makes it easiest for the user to configure. diff --git a/website/developer-docs/translation.md b/website/developer-docs/translation.md index ce2191a56..cfadcb068 100644 --- a/website/developer-docs/translation.md +++ b/website/developer-docs/translation.md @@ -1,11 +1,15 @@ --- -title: Translation +title: Translations --- Translation in authentik is done in two places. Most of the text is defined in the frontend in `web/`, and a subset of messages is defined in the backend. The frontend uses [lingui](https://lingui.js.org/), and the backend uses the built-in django translation tools. +:::info +Please review the [Writing documentation](./docs/writing-documentation) guidelines as they apply to documentation too. +::: + ## Online translation To simplify translation you can use https://www.transifex.com/beryjuorg/authentik/, which has no local requirements. diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js index a3a06ae1a..468cd6840 100644 --- a/website/sidebarsDev.js +++ b/website/sidebarsDev.js @@ -26,5 +26,9 @@ module.exports = { type: "doc", id: "translation", }, + { + type: "doc", + id: "docs/writing-documentation", + }, ], };