About category „Howto“ and writing guides

Tutorials and Guides
1

Thanks for considering to write a howto/guide for installation, configuration, programming,… here and share your knowledge :heart: This is what makes a community!

Where to start

Discourse provides the possibility to create topics as wiki entry. These can be edited by other members including a revision history.

Just create a new topic in here. If you want to edit an existing wiki entry, you’ll recognize the Edit button in the lower right corner.

Requirements

  • Add the original author/maintainer
  • Add a short revision version e.g. v0.1
  • Tested with specific versions
  • Use Markdown only (and some HTML if needed)
  • English only – perhaps consider using an online translator like DeepL if needed
> Author: @originalAuthor
> Revision: v0.1
>
> Tested with:
> - Icinga 2 v2.11.2-1
> - Icinga Web 2 v2.7.3

Structure

Howtos should provide structured headings (just like this topic). Could look like this:

# Introduction

# Requirements
## Linux
## Windows

# Installation
## Webserver

# Configuration

# Conclusion

# FAQ

Content

Please keep in mind: you are probably very familiar with your topic, everyone else is reading about it now – maybe for the first time! So don’t hesitate to note everything, even small steps you may consider superfluous. Avoid assuming things as known.

Make sure to format code blocks, installation commands, logs with code tags in Markdown as it enhances readability a lot; Discourse renders Markdown in your browser as you type. When in doubt, find assistance in writing Markdown here and here.

URLs, images, headings, bold, italic, etc. also enhance readability.

Let Open Source projects inspire you in terms of writing docs and using Markdown :slight_smile:

Review

Ask other community members to review your howto.

If you find any howto which is outdated, do the following:

  • If it is just a typo, edit and fix it.
  • If you want to propose a (breaking) change, reply to the topic and discuss it with the original author.
  • If it is outdated and there is no reply within a month, edit it and mark it as outdated (with a gentle emoji)

Questions?

Just write a reply!

And now?

Happy editing! :slight_smile:

Cheers,
Marianne