Source originale du contenu

New York's hottest web framework is unicornThunderstorm.js. It has all the doodads you need to foo and bar your components with server-side tomfoolery. It's easy, just plug and play! Connect the flux capacitor to the spiderpug and you'll be abstracting over your synapses.

That's what I see when I read most READMEs for the first time. A lot of cool technical words mushed up into something to make people want to use your product. But, offers no real explanation about what it does.

Of course, we have to entice people to use our thing, I'm sure there must be more detail further in.

Just do 'sudo npm gulp rubygems' and you're ready to go!

Oh, ok.

This is a post about the walls we've built around our projects. Frolicking about in our bag of tricks, whilst others are trying to dig into our castle with a rubber teaspoon.

Here are some tips to make the process easier.

Documentation Driven Development

No functions, models or tools should exist without being documented. We often lose track of what we're doing, so I suggest writing your documentation first. Have a loose outline of what you want to achieve, so you can keep track of what you intended to do. Once you've written the code you can make any changes you need and flesh things out.

Many open source projects wont let you contribute code without having written tests first. I say the same should go for documentation. Documentation can become outdated so quickly, encouraging all contributors to keep documentation in mind from the outset will slow the ageing process greatly.

Language

Language is the most difficult thing to get right. As someone writing documentation, you have to create something understandable to everyone.

By default, your writing should be understood by individuals with a 12-14 year reading level. There are tools you can use to help you with this such as Hemingway Editor, which I used to write this post.

Avoid use of "easy", "simple" and "just". If you tell me something is easy and I don't understand it, I feel alienated. What is easy to you is not easy to other people. Avoid phrases like "so easy your gran could do it". My nan has no interest in using your Rails plugin. Nor, does she appreciate the implication that you simplified things especially for her.

Demos, Demos, Demos

You need demos. Anything from small snippets for your API methods, to full blown tutorials.

Have different demos to offer different contexts of use. As humans we struggle to grasp how to use something if we're not shown how to do the thing we want to do exactly. A few different tutorials gives variety and invites more people in.

If you can, have your demonstrations use different mediums. Whilst one person can get all the information you need through reading, another wont be able to grasp the concept until they've seen a video. Naturally, all videos and audio content should have subtitles/transcripts.

Be active in the community

Make yourself available to answer questions. I work with several open source communities and each have open Slack/IRC channels. One has a bot in their chat that alerts them to new Stack Overflow questions related to their framework. One has regular office hours every day and a dedicated FAQ application. All are active on Twitter and dedicate time to answering GitHub Issues.

My suggestions can be expensive in time, money and energy. When you're building something for the first time, all of this comes down to you. Focus on the documentation in the beginning. By doing that, you'll create a welcoming place for others and then they can start helping you with the rest of it.

It's okay if you don't get it right the first time. It's never going to be possible to have everyone understand your project right away; but at least replace my spoon with a shovel.