API doc code first vs api first

[pratikdas]

Please read through the writing guide before submitting a pull request and go through this checklist (at least for your first article).

Feel free to raise the pull request even if the checklist hasn't been worked through, yet, to take advantage of the online preview that is generated for each pull request (see "deploy/netlify" under "Show all checks" in your pull request). But please only flag it to be reviewed by your editor after going through the checklist.

Review

• you have reviewed the text a day after finishing it (you'd be surprised how many errors you can avoid by just getting some distance to what you've written)

Content

• the article explains why and not only how
• (half-)sentences that express a meaningful idea that is understandable by itself own are bold to allow quick scanning of the text
• the text has been checked with Grammarly (the free tier is enough)

Text

• the text is conversational ("we" instead of "you", easy language)
• there are no "walls of text" (short sentences, short paragraphs with a single idea)
• the text is inclusive ("the developers" and "they" instead of "the developer" and "he/she")
• the text uses active voice instead of passive voice
• names are spelled consistently throughout the article (correct uppercase / lowercase)
• file names and variables are highlighted as code

Structure

• the article has a short intro before the first headline
• by reading the table of contents (TOC) alone, I get a sense of the "story" of the article (check the TOC in the preview after raising the PR or by starting the blog locally on your machine)
• if using sub-headlines, there's at least two sub-headlines below a main-headline
• headlines are consistent throughout the article (same level of abstraction, same style - if one headline starts with a verb in imperative form, the other headlines on the same level should probably, too)

Code Examples

• code examples are introduced with a ":" and explained below the code example
• code examples are formatted to avoid horizontal scrolling (manual line breaks and 2-spaces indentation)