Editing code samples in documentation: what I check before they ship
When I edit a page of documentation, I used to skim past the code blocks. They looked technical, someone had presumably tested them, and my job was the prose around them. That was a mistake. The code samples are often the only part of a page a reader actually uses. Many people jump straight to the first grey box, copy it, and paste it into a terminal. If it fails, the clear paragraph above it…
When editing documentation code samples, it's important to thoroughly review each sample to ensure it functions as intended. This includes checking if the code can be copied and run without modifications, ensuring commands and output are separated, and using clear placeholders for user input. Additionally, the text and code should match line by line to avoid discrepancies caused by updates.
Finally, strive to keep samples concise and only include the essential lines required to demonstrate the concept. Automation through scripts can help enforce these checks in a docs-as-code setup.
Brief written by urgent.news from Dev.to's own syndicated text. Machine-written — may contain errors; check the original before relying on it.
