How To Write Documentation For Your Apps

Main ideas / lessons conveyed

• Documentation is something the creator should build while developing the app, because it reduces setup friction for others and will likely be needed again in the future.
• Studying existing tutorials and documentation helps, but the creator still had to “develop their own documentation” based on their app’s needs.
• Use a documentation framework/tool to speed up setup and improve structure, rather than building everything from scratch.
• Good documentation should be clear and developer-friendly, using readable structure, code snippets, and supporting media.
• A practical writing approach (a 3-part process) improves documentation quality, especially for complex setup flows like OAuth.

Method / workflow presented (detailed)

1) Choose a tool/framework to generate the documentation site

The creator used Nextra:

• It provides templates that make documentation creation faster.
• Suggested process:
  1. Go to Nextra.
  2. Use the deploy/template flow.
  3. Create a repository.
  4. Deploy it to Vercel.
  5. Use the starter template (a Next.js app with MDX).

2) Configure the documentation structure (sidebar/pages)

The creator edited meta.json to define the main pages of the documentation.

Example pages/sections included:

• Introduction
• App setup
• Dashboard
• Authentication
• Stripe
• OAuth-related chapters such as:
  • Google OAuth
  • GitHub OAuth

Effect: the sidebar/routing automatically reflects the pages defined in meta.json.

3) Write documentation content using MDX/Markdown concepts

Documentation pages are authored as MDX (Markdown + JSX-like capabilities).

Basic concepts described:

• Create an index.MDX for the main page.
• Use Markdown-like syntax, such as:
  • Headings (e.g., # for top headings)
  • Paragraph text in plain English
  • Images (referenced via image files like main.png)
  • Subheadings (e.g., ##)

4) Write the actual documentation with a “3-step” approach

The creator summarizes their “best thing” as three main steps for creating documentation:

(A) Break content into different chapters

• Don’t combine everything into one page.
• Example for Authentication/OAuth:
  • Separate Google OAuth chapter
  • Separate GitHub OAuth chapter
  • Include chapters for:
    • prerequisites
    • obtaining environment variables

(B) Display code and text as much as possible

For setup instructions, include:

• Step-by-step instructions per chapter
• Environment variable formatting (including what an .env file looks like)
• Terminal commands (e.g., shown as a bash code block)
• Copyable snippets users can replicate in their own app

Goal: reduce ambiguity and help developers implement quickly.

(C) Include videos/examples and/or images where code can’t be shown

• When instructions involve UI steps that don’t map to copyable code (e.g., clicking buttons in provider dashboards to obtain keys/secrets), use images.
• Example:
  • For OAuth setup, images are used to show how to obtain GitHub Client ID and Secret ID.
• The creator used this image approach across:
  • OAuth setup
  • dashboard sections where screenshots are more meaningful

5) Example organization for Stripe (structure pattern)

The creator highlights Stripe setup as an example of how users should navigate:

• User clicks something like “Stripe”
• Then follows a step-by-step guide that includes:
  • videos/titles/chapters (as relevant)
  • the exact code needed for Stripe integration

Overall structure of the “starter documentation” shown

• Starts with an Introduction page.
• Then sections for major app features:
  • App setup
  • Dashboard
  • Authentication (with OAuth subsections)
  • Stripe
• Each topic uses:
  • a clear chapter structure
  • code blocks/snippets where applicable
  • images when UI-only actions are required

Speakers / sources featured

• Speaker: “Nazar” (the creator, referred to multiple times as “Nazar”)
• Referenced source/tool: Nextra
• Referenced creator/video source: Web Dev Cody (where the Nextra tool was found)