This is good advice! I would like to propose a corollary:
If your main API function has multiple parameters, in the documentation example you need to use all of them, and absolutely do not shadow the parameter names! “foo foo = foo” might make your demo look slick, but the developer learns nothing. This is a lost opportunity to explain the parameters with the variable name instead of a comment.
I’ll give an example: RevenueCat’s demo for using SyncPurchases [1] returns a tuple of (value, error), and they throw away the error, not even showing the 1 line of how you have to typecast it. This results in much digging needed.
[1] https://www.revenuecat.com/docs/getting-started/quickstart#4...
> foo foo=foo
I hate those. I always make an effort to avoid using the same name for different things, e.g. MyParamName=MyValue indicates clearly that the two concepts are different and can be independently customized.
While we're on the topic of "Terrible "quick start" documentation, checkout the Wix Toolset "Getting Started" docs:
https://wixtoolset.org/docs/intro/
You learn how to install a tool, and then um, check it's installed?
Not a single example of how to run it, how to use it, or how to actually build a installer using WiX.
If you follow the links [1] you end up in reference documentation, the kind where it tells you a hundred different command line flags, none of which mean anything to someone getting started.
Ah, you realise you somehow skipped over "Tools and Concepts" [2]
Nope! That's just an empty header, which takes you to either a FAQ or jumping into "Burn bundles".
Like, all you want to know is, "I have console applications A and B, referencing library projects X, Y, Z, how do I put them in an msi installer?"
And the docs just don't provide that level of help.
By far the worst kind of documentation is this kind of "Technically correct" documentation, half-generated from doc-comments that might work okay as a reference for someone who has worked with the product and needs to remind themselves of a flag, but it's impenetrable otherwise. I don't miss the days when the whole of MSDN was like this.
As a bonus in the case of WiX, there was a huge breaking v3 to v4 change, so half of the guides / stackoverflow questions out there are for the outdated version. And the newer version appears to be maintained by a company that wants to monetise support.
Then mix in the .NET Framework / .Net core migrations on top, as well as installers being kind of old-fashioned compared to containerising everything, and it feels hopeless to try.
Whenever I'd hire someone new into DevRel at DigitalOcean back in the day, they'd always ask to see my demo.
I'd spin up a droplet and ssh in. I never took the full 10 minutes in the demo's for conf's we sponsored. 1.5 minutes and you can go watch someone else more interesting than me.
Get to the aha moment and get onto the next group of potential customers.
That's the importance of a good landing page or Readme.md
Tell me why I should care and assume I don't want to.