from Hacker News

Developer docs: What do you like to see first?

by advaitruia on 7/26/22, 5:17 PM with 6 comments

When using a new product, there are 2 types of information in the docs

1. Guides: Information that helps you implement the product / try it out 2. Education: Information that helps you understand the product, what it does, why its good etc

When you're browsing a product for the first time, what do you think should be a good balance between these two?

Which companies do you think get this most right?

  • by wruza on 7/26/22, 5:53 PM

    Synopsis first, with real examples. Rather than reading through parts of guides which are either irrelevant or already known, I like to see what it does, as in code/config with comments. When searching for a developer’s product I already know what I’m looking for and how it might look like. Synopsis gives a rich picture, which (even if not very clear in details) either matches expectations or does not.

    Guides are good for learning, manual references are good for referencing to details. Synopses are good for wading through possible options and not wasting your time. Landings are idk what for, most landings are useless marketing nonsense. Delete it, add some examples.

    Good example: https://lesscss.org/

    Mature, industry approved, feature rich, stable and powerful professional makes your hair silky and smooth example: https://sass-lang.com/

  • by beardyw on 7/26/22, 6:07 PM

    Whilst I agree with the importance of a guide, I think the reader first needs clarification of what this thing is and why it exists. It doesn't need to be much but it reassures you that the investment of time you are about to make is worthwhile.

  • by armchairhacker on 7/26/22, 5:22 PM

    Both a guide and a manual. The “guide” is for newcomers and later sections will teach the more advanced techniques. The “manual” is everything in-depth, specifications, docs organized by symbol etc.

    This is how most sites do things and my preferred way

  • by username_exists on 7/26/22, 5:31 PM

    Definitely like to start with a guide, then manual. I'm not sure I agree with the distinction made between Guides/Education. Guides should definitely educate, but just at a higher level of abstraction.

  • by duped on 7/26/22, 6:30 PM

  • by MahajanVardhan on 7/26/22, 5:28 PM

    Just do what stripe does. also, +1 for guide then manual.