Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

 

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

There are different types of developers each with their own habits and processes. In this blog, Danae Miller-Clendon, a web developer from Toast, classifies the types of developers and their methodologies to documentation. Read more to find out which classification you fit into.

Read post

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.

Dice in hand

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.

About the author
Danae Miller-Clendon

Danaë is a web developer working for SilverStripe partner, Toast, in Takapuna. When she isn’t shoulders-deep in code, she enjoys sewing, swing dancing, and singing in a choir. She hopes these hobbies will actually become useful one day.

Post your comment

Comments

  • @Morven - It certainly can be a challenge! Often you'll want to write it perfectly the first time, which will only hold you back from starting it at all. I find good documentation evolves as your module would - don't sweat getting it right the first time, or even knowing what to document. As you use and work on your module, or as feedback comes in from the community, you'll find it easier to decide on what to write.

    As for the chaotic evil developer, who knows? It's best to be prepared. Urban legends tend to be based on fact...right? ;)

    Posted by Danae, 05/02/2018 9:31am (6 months ago)

  • I have to admit, I find writing documentation the hardest part of writing modules. I try to at least write a comprehensive readme for modules I put out. But sometimes it can be hard to know what to document!

    Not really sure I have seen any examples of the "chaotic evil" developer. Do they actually exist, or rather an urban legend?

    Posted by Morven Lewis-Everley, 19/12/2017 10:54pm (7 months ago)

RSS feed for comments on this page | RSS feed for all comments

Like what you have read?

Sign up for our weekly blog digest sent to your inbox.

Subscribe