Writing great documentation

Another important recommendation is to simply write great documentation. There's nothing worse, I feel, as a developer, than to have to dig into the code to understand how a module works; it's like having to lift the hood of the car to understand how to drive a vehicle!

Get good at writing English to convey technical ideas! I really think it's a skill that every good developer really needs to master.

Grabbing yourself a Markdown editor

Puppet modules use markdown for their documentation formatting. So it makes sense to use either a standalone Markdown editor, or some plugins for your IDE, so that you can create your quality documentation appropriately. Following on from our selection of code IDEs that we considered earlier in the chapter, the corresponding markdown plugins follow.

Vim

You can use the vim-instant-markdown plugin (https://github.com/suan/vim-instant-markdown) if you're a vim fan.

TextMate

You can use the TextMate markdown bundle (https://github.com/textmate/markdown.tmbundle) if you enjoy the Apple look and feel of TextMate.

Atom

If, like me, you enjoy using Atom, you can use the Markdown Preview Plus package (https://atom.io/packages/markdown-preview-plus).

Visual Studio

If you're a developer in the Windows and .NET world, then look no further than the Markdown editor extension (https://marketplace.visualstudio.com/items?itemName=MadsKristensen.MarkdownEditor).

Standalone Markdown editors

If you would rather use a standalone Markdown editor, I can recommend personally MacDown for macOS X. My (very) short list of standalone Markdown editors for various operating systems follows.

Remarkable

If you're using Linux, then Remarkable is probably the best standalone editor. It also works on Windows. Some of its features include live preview, exporting to PDF and HTML, GitHub markdown, custom CSS, syntax highlighting, and keyboard shortcuts.

MacDown

If you would rather use a standalone Markdown editor, I can recommend MacDown for macOS X, which is free (open source). It's heavily inspired by Mou, and is designed with web developers in mind. It has configurable syntax highlighting, live preview, and auto-completion. If you're looking for a lean, fast, configurable standalone Markdown editor, this might be the one for you.