Using code, markup or command examples in your Wiki articles can be very helpful to readers. Examples often help to clarify the steps required to complete a task. From a reader’s perspective, being able to read example code or markup can be the difference between understanding and not understanding the subject of the article.
It's important then that you take time to format your code examples so that they are readable and easy to understand. Here are some tips to consider when you add code, markup or command examples to your articles.
1. Use variable names that are descriptive (unless the use of the variable is very clear)
2. When you copy code, always copy it from the source editor (e.g. Visual Studio), into a notepad editor first. This strips out any formatting. After copying it into the notepad editor, remove unneeded carriage returns and fix the tabbing and spacing. Finally, copy it out of the text editor into the Wiki code formatting editor (or whatever other code formatting tool you're using).
3. The Wiki code editor is pretty good, and caters for a range of languages. There are some exceptions though, where it's better to use another editor. PowerShell is one of these exceptions. There is a great article (referenced below) on using the PowerShell ISE editor to format PowerShell snippets.
4. Formatting XML can be tricky. The Wiki code editor allows you to add XML code blocks, and it does a good job of colourising it. However, for the XML to be readable, it requires that you properly format the XML markup before adding it to the editor. One tool I find very useful for formatting XML is the XML Tools plugin for Notepad++. This plugin allows you to linarize XML (remove all carriage returns and spaces), and then reformat it with the correct tabbing and carriage returns (see the article below).
5. Always test your code examples. People reading your articles are looking to learn something – do your best to make sure your code examples work!
6. Anonymize your code examples; remove references to yourself, your company or the client you worked for! Try to keep code examples as generic as possible.
7. Consider adding comments to your code examples. It helps a reader understand the code example if it's clearly commented.
See these Wiki articles for some helpful examples
Other Posts in this series: