“Sell” your work to your users. And write documentation !!!

So you’ve just finished implementing the greatest software you’ve ever made. You are overwhelmed with joy and can’t wait for the first million of users to discover it.  You finally release it, spread the news around so that even the pope knows your work is out there. You monitor your website and visitors are pouring. And yet…

The missing piece

And yet it appears your software is not adopted as much as expected. Visitors end up using another framework or application instead of yours. Of course there might be a number of reasons for this. Maybe they are afraid of the release version: 1.0.0, there might be bugs left in there. Maybe they don’t want to change their habits, why should they? Maybe they they simply don’t get why your software is better, what it does that the other does not.

So how about convincing those visitors to try your software? You should sell” your work to those users. Be a showman! “Step right up ladies and gentlemen! Allow me to show you the most incredible software you’ve ever seen!”.

And that all comes down to documenting your application by:

  • Using a marketing, in-your-face approach: grab their interest, make that first contact count.
  • Making it easy for them to learn how to use your software: write a manual, make the API available, write tutorials.

The Barnum effect

The first contact your users have with your application (after reading a blog post on DZone about it) is the software website. That’s where the users will get their first impression. Make no mistake, this is your first step to documentation: you gather up the most important aspects of your application and you write them down, bringing them forward so that the user understands what this is all about.

Let’s take Spring for example.

a screenshot of Spring's main website page
Spring IO’s clean and to-the-point website

When you access their website you are presented with a clear, to-the-point page that displays all you need to know. A catchy tagline, followed by a brief summary of what the framework suite does and who it is for: it’s for developers, it will help you building JVM based systems and applications. That’s it, you’re hooked!

Look at the links in the header above: the first one is “DOCS“,  and the one after is “GUIDES“. I’m betting that’s not an accident!

Another great example of clear and to-the-point introduction is Jodd. The catch-phrase is not only funny (a reference to “The Unbearable Lightness of Being” movie) but is also gives you hints: it’s going to be about Java, and it’s going to be light. Of course it also provides a quick and clear summary of what Jodd is for, social links right above it, and header links to take you to the crucial parts of the site: the download page and the documentation page. Yep, documentation is crucial.

a screenshot of Jodd's main web page
Jodd’s excellent first page

By the way, have you noticed how both these sites are responsive and adapted for access by tablets and smartphones?

Have a look at OpenOffice and LibreOffice as a final example. Both websites appear to be clear and uncluttered on first approach. But which one is the most marketing-oriented one? Which one is the catchiest? I’ll let you be the judge of that:

a screenshot of OpenOffice's main website page
OpenOffice’s main web page
a screenshot of Libre Office's main website page
LibreOffice’s website

But seriously, where’s the manual?

So you have convinced your potential users that they should really look into your product. But now they want to learn how to use it. You can of course direct your users to your GitHub page, where you have duly documented (the most important bits, but probably not all of) your software. This might work with developers, maybe. But honestly, even as a developer I’m not really attracted to this:

crossroads.js github page screenshot
GitHub pages are not really the most inviting. They are meant to be functional

Which is probably why the author of crossroads added this website:

This is much more inviting!
This is much more inviting!

The whole API is described by scrolling down that page, full with code examples. That’s perfect for the developer and it really builds the user’s confidence in the product: “if the author of this framework has put that much work into his website and documentation, his product must be stable and well-conceived!”.

That works for small frameworks, but if your software is a much more complex beast you have no other choice than writing a full-fledged manual.

I remember being impressed by Vaadin‘s documentation. The authors made sure to write a full “Book of Vaadin” which regroups everything from an introduction to the product up to the nitty-gritty details. What more could one ask?

I wish I had that kind of documentation for Maven! Come on, I know I have not been the only one cursing the website for being unable to find that elusive bit of info. I usually end up digging some StackOverflow article to get an answer. This is not how it should be, don’t you think? In that respect, Gradle is doing a much better job!

Spring and Hibernate, to name but a couple, also made huge efforts to provide a great amount of well-organized information. Though they’re both overlooking one small but important aspect.

I meant the offline manual…

Spring and Hibernate are not the only ones, mind you. Many software authors forget how important it is to have a nice offline alternative to the HTML manuals. There are many situations where one would like to access some reference document without having to be connected. Even Bootstrap users seem to be asking for offline documentation!

Take for example the Spring Framework. I have found no reference to a PDF version of their very well-written manual. To obtain that, you actually need to fiddle with the reference docs URL:

So THAT’s how you get the PDF manual !

At least Spring Boot gives you a link (inside their html manual!) that points to a PDF file. However Spring Security does not even provide  an offline solution!

Offline manuals are nice. You can carry them anywhere whether you are connected or not. As an example, I had Spring Framework 4.1 in PDF form on my tablet during my holidays. I was camping, so having access to a good WiFi connection without forking out a surreal amount of cash was not an option, so at least I was able to catch up with Spring’s latest features while enjoying a tan on the lake. Isn’t that bliss?


I believe the quality of a software’s documentation, regarding its presentation (the website), its introduction (tutorials or guides) or its references (manuals and API), will determine whether people will decide to use it or not.

The better your documentation, the more your readers (and potential future users) will adhere to your ideas, your application or framework’s conception. Whatever energy or passion pushed you to pour endless hours on your creation should transpire through your documentation!


Well, I’ll try to throw a few ideas in a forthcoming post. In the meantime, if you have any examples of exceptionally good software websites or software documentation you want to share, why not share them in the comments below?

Until then… Cheers!