Guidelines for writing howtos


(Michael Friedrich) #1

Thanks for considering to write a community howto and share the knowledge :heart:

Where to start

Discourse provides the possibility to create posts 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 button :wink:

00

Requirements

  • Add the original author/maintainer
  • Add a short revision version e.g. v0.1
  • Use Markdown only (and some HTML if needed)
  • English language
> Author: @dnsmichi 
>
> Revision: v0.1
>
> Tested with:
> - Icinga 2 v2.8.x
> - Icinga Web 2 v2.5.x

Structure

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

# Introduction

# Requirements

## Linux

## Windows

# Installation

## Webserver

# Configuration

# Conclusion

# FAQ

Content

Make sure to format code blocks, installation commands, logs with code tags in Markdown.

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

Discourse renders Markdown in your browser as you type.

More tips on writing Markdown can be found here. You can also look into various open source projects how they write their documentation in Markdown, e.g. https://github.com/icinga/icinga2

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, 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?

Reply here :slight_smile:


New platform (work in progress)
New platform (work in progress)
Icinga Installation Best Practice?
(Michael Friedrich) #2

Welcome to our #monitoringlove platform