Wiki: Technical Editing

Wiki: Technical Editing

This is a list of typical things that you can do right now, to get started helping out at TechNet Wiki.

List of Checks for Every TechNet Wiki Article

Please add the checks you normally do, so we can all work together for a better Wiki.
 

1. Tags

There are obviously thousands of tags in the Wiki. Here is a top list of the most common and important tags you can check for:

You may find other common tags in this article Wiki: Common Tags.
Common technology tags in this article TechNet Wiki: Technology Tags

 

2. Content

  • Article title in "Title case" (e. g. not all CAPS)
  • Spelling and grammar
  • Enhance the "See Also" section
  • Tidy formatting, like paragraphs and proper headings
  • Remove common abbreviations used in forums messages such as BTW, AFAIK, IMHO from the articles - such abbreviations should be spelled fully
  • Try to make sure that technical abbreviations used have a link explaining them to the person who may not be familiar with the technology
  • Pay attention to the language and avoid slang or jargon expressions, try to use clean language 

3. Layout

  • Add Table of Contents marker ([TOC]), when needed (the article has enough body and structure)
  • Add a See Also section
  • Use proper casing (NOT ALL CAPS) for
    • titles (use title casing)
    • headers (use title casing)
    • tags  
  • Use default fonts, colors and layout as much as possible (to keep consistency)


4. HTML

  • Check HTML tags (like nested or deformed header tags) and other broken/useless HTML
  • Check Code section - it is better to use Code block button with appropriate language
  • Check correct RGB color names (not values) are used - this is for Advanced Editors
  • Make sure the header <a name=> tags don't include the number "0" (zero). If the header includes the "0" number, then the <a name=> script includes the zero and then the header doesn't appear in the TOC. So just remove the "0" from the <a name=> script. For example, change "<a name=SQL_Server_2008></a>" to "<a name=SQL_Server_8></a>" instead.
  • If you see a table which has columns cut off on the right side, you may try fixing it by adding the following tag <div style='overflow:scroll'>table here</div> (thanks to Tord Glad Nordahl for this tip)

 

5. Improvements

       
  • Any additional content that advances the article
  • Links to other articles, especially in the See Also section
  • Comments on the article - encouragement, congratulations, questions or criticisms


Combining Edits

We need to emphasize, that when you're editing an article, even if you initially came to just fix an incorrect tag or add a tag, it may be a good idea to read this article as a whole and see, if there are other things that may need fixing such as typos or bad formatting. This way, you do most of your edits at once. If you do a lot of individual edits, it might make the author or others think that you're trying to do that on purpose. So it's best to combine edits, when possible.


Community Blogs



See Also


Others Languages



This article is featured in the WiKi Ninja blog Wiki Life: Technical Editing
Sort by: Published Date | Most Recent | Most Useful
Comments
  • Must see article for new editors... Thanks for writing it!!!!!!!!!!!

  • We discussed the question of tags in the Council and decided to use singular. So, even if article has several comments, the tag will be 'has comment' and even for several images the tag will be 'has image'. I'll discuss 'has links' tag separately. But for the two common tags has image, has table, has comment - use singular. The See Also should be separated by horizontal line. However, don't make these edits only - make other edits as well. In other words, don't try to perfect every article in very little detail - try doing changes in mass (few edits at once).

  • Great article! This guidance is much needed and important.

  • It is exactly what I am looking for.

    Thanks so much!

  • Naomi added this to the Guidelines Portal: social.technet.microsoft.com/.../compare.aspx

  • We may want to have a separate discussion or a WiKi article on Tags. For now, in our recent Council chat we decided to not use 'has links' tag at all and use singular for 'has image' and 'has comment'. That's all we know for now. If you come across an article you want to edit, you may keep this in mind. But don't go for these changes only, we plan to standardize the tags at some point.

  • Thanks, Naomi!

  • Naomi and I just added the "Combine Edits" section to make a best practice that we should be combining edits, when possible, versus making more individual edits. Thanks for reading!

Page 1 of 1 (8 items)