omg it's a quick start guide

· 319 words · 2 minute read

We pushed out the quick start guide today. It’s a “zero to something you can use” document.

I’m fairly sure the community is mostly people who are comfortable seeing what this button does. Those folks probably also know what Markdown is, have come across the Markdown-with-front-matter pattern, and have probably dropped a few commas or left a few brackets unclosed in a config file in their day.

But there are also people who may have sat blogging out during its heyday, or blogged but stuck to platforms like WordPress or Blogger, or who just want some documentation to work with before jumping in.

This guide is written more for the latter audience.

I like the approach Adam has taken with

If you wanted to stick to the core offering you could do that and have a simple, functional blog. Authoring is simple, and it’s cool that it does some stuff implicitly (e.g. setting a post title using the first Markdown h1).

At the same time, he’s written an API that’s amenable to making tools for it and there’s a git-based workflow if you prefer to work that way. I’ve seen some very nice blogs from people who know their way around CSS.

Personally, I enjoyed the writing exercise. My favorite writing during my time on LinuxToday, LinuxPlanet, and Practically Networked all involved writing howtos and little tutorials, and my biggest contribution to the Puppet docs was a getting started guide on Hiera. It took months to learn enough Puppet to learn enough Hiera to explain it credibly, and it was all fun.

I enjoy learning how something works then writing that down with an eye to helping other people along, and it turns out that’s a useful skill to have for everything from telling people what that button does when you click it to explaining and directing an organizational design change for a 200-person R&D organization.