Wiki life: The Importance of TOC

Dear All,

Welcome to TechNet Wiki Life, in this blog post we will see in detail of why we need to add Table of Contents (TOC) and what should be avoided while adding Table of Contents (TOC).

TOC stands for Table of Contents,  and in Wiki it is an automated Header collection which will give a quick glance on your article and also used for navigating to header section by clicking on each header in TOC. TOC will have all our header and sub header’s of article.

Adding TOC to our article is very simple, while editing or writing our article in TechNet Wiki editor. Usually a TOC is inserted in the beginning of a document, but you also can set it after your introduction. Typically in the first line of the editor, add the code [TOC] (<opening square bracket>TOC<closing square bracket>, without spaces!) in your document.

TOC1

For adding content in TOC in each header and sub header we need to use the header <hx></hx> tag (where hx is h1, h2, h3, h4, ...).

For main header we need to use the <h1></h1> tag for example <h1> Getting Started </h1> from html design or Select the header text and Select the Heading 1

TOC2

For Sub header same like above but select the heading 2 options.

TOC3

Here is the TechNet wiki article link which explains in detail about How to Automatically Add a Table of Contents (TOC) to a TechNet Wiki Article

Why we need to add TOC?

Let’s consider an example to explain why we need to add a TOC for our article. We write articles for community, how we are presenting our article is very important. Our article can be short or long, three main things we should always be consider before writing article.

  • Pick the right Title for our article
  • Give the appropriate heading for each section of explanations.
  • Add TOC

1) Pick the right Title for your article

 Picking the right title is very important for each article. Community members will be interested to read article by the title. Our title should be meaningful and relevant to our technology.

In title always include as WWW here WWW stands for What, What and What

=> What Technology the Article Explains + What Example are you explaining + using What Programming

Here is few of my article title with WWW  

ASP.NET Core1.0 Insert/Select to Database Using Angular2 and WEB API

MVC Dashboard with Chart using AngularJS and WEB API

The importance for adding WWW is community has all technology users, if we include the Technology and what programing we are explaining, it will be easy for the members to filter our article to read and get benefit, another important factor is for google search, Mostly community members will search there needed topic from TechNet and also from Google, if we have given appropriate title for our article, in search our article can be list in top.

2) Give the appropriate heading for each section of explanations

Now we have given appropriate title for our article what’s next. Before writing article always plan what you are going to explain, Think as a reader’s point of view before writing any article, first make one standard template with headers and use the same format template for all article writings.

For example I will use this standard template for all my articles.

  • Introduction (Explain about what this article for and what readers can get benefit from this article. If needed add reference links and read also )
  • Features (If your article explains about some specific features)
  • Prerequisites(If any prerequisites need for the article give the link for download)
  • Source Code Download Link (This is very important for each article)
  • Code Part Explanation (This is another important part of our article, The readers should understand well about what you have explained and how to work with the sample so always give step by step explanation of code part from Project creation till Run the program. For example read my article which gives details step by step explanations in code part ASP.NET Core1.0 Insert/Select to Database Using Angular2 and WEB API )
  • Output(Give explanation of your article result with images)
  • Conclusion
  • See Also (If any other TechNet Wiki article explains similar to your article add the links)

3) Add TOC

If you ask me now we have given appropriate title and added all heading for our article then why we need to add TOC. The answer to this question will be simple as how we are presenting our article to community users. We write articles for community members to be got benefit. Let’s consider we have added appropriate title and added headers for each section and if our article is long. Every time members need to scroll from top to bottom to read our entire article. If members are more interested to read our article middle section , again they need to scroll till down. If we add the TOC it will be easy and convenient for members to read our article by headers sections. By adding TOC members can be easily identified the topic’s which our article covers, this will make more interest for readers to read our article.

Don’t forget to add Back to Top under each section to avoid using scroll.

What should be avoided while adding TOC?

Always write detailed explanation under each header part, don’t add one line explanation under each header. Sometime article writers will give very good header with only code part. Think when the end user clicks on TOC heading and not find any explanation or one line explanation without details. How they can understand what the header explains about .So always avoid one line explanation in our article and give as much as valid information in our article.

Avoid zeros in header
Also, better not use a '0' (zero) in the header, because there is a known issue with the TOC generation. If you can't avoid it, you must edit the HTML to remove the 0 in the header link name (you can replace the zero with O (oh), eg <a name="0_issue"> with zero can be changed to <name="oh_issue" ).

Short headers
And last but not least, keep your headers SHORT.

Our main aim for writing article is all our community members should get benefit, so always think in member’s point of view before writing any article and give as much information as you can with detailed explanation. 


Hope you all like this blog post.

If you have any question's kindly leave me a comment. To know more in detail check all this links.

See you all soon with another blog post :)


Thank you all

Your’s

Syed Shanu

MSDN Profile | MVP Profile | Facebook | Twitter |