Content guidelines
We think it's awesome that you want to contribute to this site! ✍️
Everything contained here is available on the public internet, so having a few guidelines is important to ensure a certain quality.
Phrasing and style
These pages are primarily meant for technical personnell, and a certain degree of technical language should be expected. But; abbreviations and phrases not expected to be well known should be described to help others learn and understand.
All articles should have an introduction which summarizes the content so that the reader knows what to expect. The introduction should avoid technical language to be easier to understand, and should convey the essentials of the subject so that other people than the developer can understand it.
Structuring an article
All articles shall have the following structure:
---
sidebar_position: N
title: Short title
---
# Short title
__Introduction__
The introduction summarizes the subject in a language understandable by all.
## Content
All articles must be technology-agnostic. Specific examples, code etc can be used, but avoid content only valid for a specific platform such as AWS or Azure - Describe the principles and not the implementation.
Use the features found in MD or Docosaurus to emphasize important elements.
Avoid a big wall of text; use logical sections to divide the content and make it easier to understand.
Use code fencing to render code correctly!
External content
Use permalinks where possible, and if it makes sense also refer to the title and author for cases where URLs are inaccessible. Archive.org might have a copy somewhere.
If content from other articles are reused, please reference them.
Help!
Need help with Markdown?
Still stuck or having a question regarding content, how to contribute etc? Please contact us on Slack or visit the following issue