[HN Gopher] Unlocking the 'aha' moment: Developer relations for ...
___________________________________________________________________
Unlocking the 'aha' moment: Developer relations for startups
Author : jonmarkgo
Score : 48 points
Date : 2024-10-07 16:40 UTC (6 hours ago)
(HTM) web link (www.signalfire.com)
(TXT) w3m dump (www.signalfire.com)
| TheJoeMan wrote:
| 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...
| xnorswap wrote:
| 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.
|
| [1] https://wixtoolset.org/docs/tools/wixexe/
|
| [2] https://wixtoolset.org/docs/tools/
| toyg wrote:
| _> 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.
| neom wrote:
| 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.
| keyle wrote:
| 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.
___________________________________________________________________
(page generated 2024-10-07 23:01 UTC)