Wiki Life: Code.Format()

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

Wiki: Format XML Markup using Notepad++
Wiki: How to Insert a Formatted Code Snippet and Code Block on TechNet Wiki
How to Paste Formatted PowerShell Code with Line Numbers on TechNet Wiki

Other Posts in this series:

• Wiki Life: Planning a Great Article
• Wiki Life: Get to the point, keep it short!

Comments

• Anonymous
  February 05, 2014
  Very good content. Congratulations Mathew.
• Anonymous
  February 05, 2014
  Excellent points there Matthew. One other thing I do in the articles that I write which applies to code based articles as well is to keep it scenario based. The scenario can be anything but keep it tangible i.e. use fictitious company, department, project and employee names.
• Anonymous
  February 05, 2014
  Thank you, Matthew, for highlighting this topic. Not every author seems to be acquainted with the "Format Code Block Tool" - although it's easy to use if your tips are obeyed. Your 2nd referenced article explains the technical part.
• Anonymous
  February 05, 2014
  Totally agree Dan, using fictitious scenario based examples is a really great idea!
• Anonymous
  February 05, 2014
  Great article!
• Anonymous
  February 06, 2014
  Well absolulty great points Matthew ( and not Craig :) )
• Anonymous
  February 06, 2014
  The comment has been removed
• Anonymous
  February 07, 2014
  I use the copy into Notepad (then into Wiki) method for Word content as well. Otherwise, you're pasting in some poorly translated HTML conversions. Thanks, Matthew!
• Anonymous
  February 07, 2014
  Yeah, good point Ed! Copying out of Word does produce some funky html!
• Anonymous
  February 07, 2014
  The comment has been removed
• Anonymous
  February 08, 2014
  Matthew, nice compilation of tips !!!
• Anonymous
  February 19, 2014
  Ctrl+C and Ctrl-X are one of the most used key combinations on my keyboard (only just out ranked by Ctrl
• Anonymous
  March 05, 2014
  There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea
• Anonymous
  March 05, 2014
  There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea
• Anonymous
  March 05, 2014
  There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea
• Anonymous
  April 02, 2014
  You just finished witting an awesome article, what should you do next? Get up from your desk and stretch
• Anonymous
  April 25, 2014
  congratulations!!!!!!!!!!!!!!!!!
• Anonymous
  August 20, 2014
  Earlier this year I wrote a series of posts about writing good articles. It's been a while since
• Anonymous
  March 19, 2015
  Due to some practical issues while switching screens during presentation, the recording of the screen
• Anonymous
  March 19, 2015
  Due to some practical issues while switching screens during presentation, the recording of the screen
• Anonymous
  September 08, 2017
  Good content.