Paul Hammant's Blog: Tutorials vs Reference Docs vs Examples

If you’re trying to promote/sell some software thing it’s best to have examples inside the “5-second rule” experience. The 5-second rule iis where people land on your article/page, scroll up and down quickly, see no examples and then hit the back button.

Some/many will do that because they’re example-orientated. That as opposed to tutorial, api-doc, or buying ideas from rant-style text. The more experienced developers get, the more likely they are to leave tutorial and api-doc as a way of gaining knowledge of a thing, and more toward examples.

And even if they shift towards ‘examples’ as a way of learning their, their standards raise too - they want something verifiable quickly. Code snippets inline in the text don’t do it for them anymore; they want a GitHub repo. Specifically a minimal buildable/runnable example of the thing they’re supposed to buy. And by minimal, I mean not convoluted with other things or boilerplate code. Say you’re trying to sell a web-framework in Java? Focus on GET/POST handlers and a RestAssured test of the same - don’t shove in Hibernate too, unless that’s one of the unique selling points (and almost no lines of code), too.

Get this right before you push your technology to the developer community. You see if your landing page fluffs that 5-second test, you’re now in the 20x place for cost of pitching to the same developer a second time, and at least many weeks from being able to do that.

A smaller group of people (including me) also get things more quickly if they pair-program with an expert on the thing. Pair towards an example-esque solution or just a directed bunch of questions. Obviously, that’s extremely high in terms of costs so you only offer it if the chances of a sale (with an ROI) are high, or you’re already in the periphery of the person you’re pitching to. Be prepared for a rollercoaster, though.

Then also, if your technology has a visible aspect, include a screenshot in that landing page. Or more than one. This is also because of the 5-second rule. I made a few contributions to www.makeareadme.com/. Know that there are about six other portals attempting to make the same arguments as that portal.