Code block Stats

Code block is the key element of any documentation. Developers often read and use code without looking at explanations around. So make sure code block itself provides enough information to be understood and correctly reused.

Writing your first Django app
Implementation
UX best practices

Implementation

1. Consider ready-to-use solutions

  • Often included into documentation engines, such as ...
  • Embed a code block widget provided by a code hosting service
  • Or create a custom widget

UX best practices

1. Highlight code syntax

  • Improve code readability by highlighting lexical tokens with different colors
  • Use one of popular libraries to highlight the code with CSS
Examples:   Gatsby

2. Show language mode label

  • Useful when your docs contains code blocks in multiple languages or environments
  • You can make the label visible only on mouse hover
Examples:   Gatsby ,   Mixpanel

3. Show code for other languages and platforms

  • Switches across similar blocks in documentation should be synchronized (using cookies)
Examples:   Stripe ,   Django ,   Stripe ,   Mapbox

4. Use comments

  • Comments allow to keep important explanations closer to code and make them visible to readers who skim through the text
  • Code blocks intended to be copied (e.g. snippet for embedding a widget) will become self-explanatory without documentation
Examples:   Mixpanel

5. Show copy to clipboard button

  • Usually shown as a "Copy" link or an icon in the right top corner. For icon show an explanation tooltip on hover.
  • Particularly useful when you provide shell scripts and show $ prefix
  • Once clicked show a message saying that code was copied
  • Copy button can be shown only on block hover
Examples:   Bootstrap ,   Mapbox ,   Mixpanel

6. Show file path

  • Usually shown as a header above the code. If code block doesn't support it show file path in a comment on the first line.
Examples:   Django ,   Auth0

7. Substitute API parameters

  • For authenticated users substitute parameter values such as project id, API endpoint, API key when possible
  • If user has multiple projects/apps allow to select one
  • Don't substitute a secret key (for security reasons), instead provide a link to get it. Substitute a test API key if possible.
  • If user is not authenticated ask them to login
Examples:   Google Maps ,   Stripe ,   Auth0

8. Don't show line numbers

  • Line numbers distract from reading the code. Only use them if you have a good reason, say to reference a particular line of code.
  • If you decide to show line numbers make sure they are ignored when code is selected.
Examples:   Stripe

9. Highlight code changes in step-by-step tutorials

  • Use red and green colors to highlight removed and added lines
  • Use "..." to skip unimportant parts of code
Examples:   Shopify ,   React

10. Show the result of code execution

  • When code block represents an important step show the reader what it does. You can embed a visual demo or even an interactive playground.
  • If you don't wish to embed them directly - just add link
Examples:   Google Maps ,   React

Apply this and many other checklists to your project