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:

Comments (20)

  1. Zeca Lima says:

    Very good content. Congratulations Mathew.

  2. Dan Christian says:

    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.

  3. Carsten Siemens says:

    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.

  4. Matthew Yarlett says:

    Totally agree Dan, using fictitious scenario based examples is a really great idea!

  5. Naomi N says:

    Great article!

  6. Gokan Ozcifci says:

    Well absolulty great points Matthew ( and not Craig 🙂 )

  7. Durval Ramos says:

    Matthew, you’re right. This seems basic but many Community members did not fully check the examples that are sharing. It’s important share articles correctly to maintain a high level of quality in TechNet Wiki.

  8. Ed Price - MSFT says:

    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!

  9. Matthew Yarlett says:

    Yeah, good point Ed! Copying out of Word does produce some funky html!

  10. Ed Price - MSFT says:

    Matthew, right. Word formatting wasn’t designed to be translated into HTML. You’ll probably notice that TechNet Wiki (and blogs) is the only platform that tries to translate your formatting. No other platform does it… Wikipedia, WordPress, Facebook,
    Twitter, LinkedIn, StackOverflow, etc. Anywhere else, they strip out all your formatting when you paste it in (so it’s like you’re pasting into Notepad). Then you have to reformat. But Wiki, Blogs, and Forums, lets you keep your formatting. It’s a bit of an
    impossible goal, so that’s why there are issues with it.

  11. Maheshkumar S Tiwari says:

    Matthew, nice compilation of tips !!!

  12. Anonymous says:

    Ctrl+C and Ctrl-X are one of the most used key combinations on my keyboard (only just out ranked by Ctrl

  13. Anonymous says:

    There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea

  14. Anonymous says:

    There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea

  15. Anonymous says:

    There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea

  16. Anonymous says:

    You just finished witting an awesome article, what should you do next? Get up from your desk and stretch

  17. hassan sayed issa20014 says:

    congratulations!!!!!!!!!!!!!!!!!

  18. Anonymous says:

    Earlier this year I wrote a series of posts about writing good articles. It’s been a while since

  19. Anonymous says:

    Due to some practical issues while switching screens during presentation, the recording of the screen

  20. Anonymous says:

    Due to some practical issues while switching screens during presentation, the recording of the screen