Concrete example first, then explanation, finally methods list

[AlessandroTambellini]

Enter your suggestions in details:

For many APIs (but not all), I find the following structure of a docs page to be really navigable and intuitive for the understanding of the API itself:

1. A commented, concrete mid-size example
2. Description of the API
3. Formal list of methods
4. (Optional) Extra info about possible nuances, flags or whatever

P.S.
It's already the 4th suggestion I report today but, given the docs are under construction, I'll take advantage of it :).
This is more of a design decision, so sorry if isn't a "structured" issue reporting

[bmuenzenmeyer]

It's already the 4th suggestion I report today

Keep them coming - we value the feedback and try to respectfully respond to all within project constraints.

This is more of a design decision

I might go so far as to say this is a source code concern with upstream docs (in Nodej.js core), not doc-kit specifically. I guess what we could explore is evolution of the spec + renderer to decide what makes sense.

[avivkeller]

so sorry

Don't apologize! You are so so helpful in this process :-)