Chaotic or Lawful - What does your documentation say about you?

At the recent StripeConNZ, I presented a talk based around SilverStripe modules. At the onset, I intended the presentation to cover the broad scope of module development, including the more technical aspects of open source sharing.

Documentation and voice was a relatively small part of the talk but it ended up prompting the most conversation in the breaks between presentations. I heard from people in marketing, freelancers, and developers working for larger companies. They all had very interesting and varied viewpoints on how documentation and brand representation online affected them personally.

The general feedback seemed to be that there isn’t too much of a focus on it during module development. Certainly you can add a README.md file to your project which will gain you points on the add-ons directory, but what sort of motivation is there to write good, concise, and inclusive documentation?

Much like my presentation, I want this blog post to start a conversation. Why should you care about the language you use in your documentation? Is it really so important to cater to new developers? How can you tell if your documentation is up to scratch?

Your Documentation Alignment

If you’re anything like me, you’ll understand my compulsion to add nerdy references to almost everything. Let’s take a look at a classic Dungeons & Dragons alignment set, but applied to the different kinds of developers you might see in the wild.

Chaotic Evil

Who is the Chaotic Evil module developer? Think of your classic internet troll. They aren’t here to help anyone. They’ve released a module, but their documentation is offensive and unhelpful. Perhaps they think it’s funny to pepper swear words all over their user guide. Most pull requests are either ignored or responded to in a less-than-polite manner.

Neutral Evil

They have a README.md file. It links to that website, letmegooglethatforyou.com, and spells out “SilverStripe Tutorials”.

Lawful Evil

The documentation seems quite well structured at first glance, but the timestamp shows the last update being over a year ago. Who knows how accurate it is any more?

Chaotic Neutral

The Chaotic Neutral developer writes documentation with their own interests at heart. If it makes sense to them, it will make sense to you, right? Bug fixes from pull requests are ignored because the Chaotic Neutral developer “would probably do it better anyway”.

Neutral

The documentation is technically there. It’s not exactly concise, but if you know what you’re doing you can probably follow it. A new developer would take one look at the line “Install this with composer” and opt for a similar module with more instruction.

Lawful Neutral

The Add-Ons module rating is the Lawful Neutral developer’s rulebook. Without bending too far backwards for the new developer, or offering too much for the advanced coder, this type of developer will structure their documentation very precisely. Their worst nightmare is a malformed markdown tag.

Chaotic Good

Bursting into Slack channels and calling out other developers for their shoddy documentation, the Chaotic Good developer has the SilverStripe community’s best interest at heart - or at least, what they believe is the community’s best interest. Their contribution activity on GitHub is through the roof.

Neutral Good

Well-structured, helpful documentation is what the Neutral Good developer strives for. They won’t go out of their way to help everyone out, but certainly won’t turn away a new developer if asked for more instructions on installing their module. Neutral Good developers tend to use their documentation to avoid Q&A sessions if at all possible.

Lawful Good

You see them in the Slack channels and in GitHub pull request threads. A Lawful Good developer will go out of their way to help you. If an issue is brought up with their code or wording in their documentation, they will fix it as soon as they are able. They strive to cater for new and veteran developers in their documentation, and would never dream of using non-inclusive speech in their user guides.

What should you strive to be?

Not everyone can be the Lawful Good developer all of the time. Life happens, and work happens, and no matter your intentions, bad documentation can stick around longer than you would like.

Take stock of the amount of spare time you have. Make documentation a priority - treat your modules like client projects. Almost no-one has time to write the most concise and helpful documentation for all of their modules, but that shouldn’t stop you from chipping away at it over time.

Start thinking about the way you present your personal (or company) brand while online. The open source community, and even just the SilverStripe community, is available to people of all abilities, cultures, genders, and backgrounds. Read the Contributor Covenant and strive to adhere to it through your documentation and personal presence online.

Small changes to the way you perceive yourself and your voice online can make a huge impact over time on the kind of responses you get for your modules. Not only does this benefit you, but it can help raise the overall quality and supportive nature of the SilverStripe community.

Having personal brand representation at the back of your mind while contributing or writing your own documentation will have you rolling nat 20s for perception in all of your SilverStripe modules.