Tutorials vs Reference Docs vs Examples
source link: https://paulhammant.com/2019/07/11/tutorials-vs-reference-docs-vs-examples/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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.
Recommend
-
62
Get started developing with the Azure SDK for Go using the developer resources below.
-
14
packages.config reference 05/21/2018 2 minutes to read In this article The packages.config file is used in some project types to maintain...
-
3
project.json reference 07/27/2017 4 minutes to read In this article NuGet 3.x+ The project.json file maintains a list of p...
-
7
Amy Berg on Twitter: "Hey @realDonaldTrump, here are some examples from my set of what convincing file folder props look like. You know, for future reference. https://t.co/QnilpY8kTC"Don’t miss what’s happeningPeople on Twitter a...
-
3
Files Permalink Latest commit message Commit time
-
11
Swift-DocC Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation. For an example of Swift-DocC in action, check out
-
4
F# documentation Learn how to write any application using the F# programming language on .NET.
-
7
New issue Docs: fix reference to a Powershell script on Windows #6936
-
1
<?xml encoding="utf-8" ??>Introduction Many Vultr Docs articles have similar steps, and repeating these details in each one creates duplicate content and maintenance difficulties. For example, a...
-
6
Ranked #17 for todayKodemoCreate interactive technical docs and tutorialsFree OptionsKodemo lets you w...
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK