Jaa

Wiki Life: How easy is it to add a table of contents?

  • Artikkeli

Wednesday is Wiki Life... what's it like actually using TechNet Wiki? We'll explore tools, processes, and oh so much more! So let's get started by talking about... TABLE OF CONTENTS!!! (I'm a former Technical Writer and Editor, so maybe I'm excited about this topic.) =^)

How easy is it to add a table of contents in TechNet Wiki? It must be pretty easy, because our Wiki Ninja is chilling...

When we began building out TechNet Wiki, several of us kept wondering about how to navigate a page. We wanted something automated, something easy.

In other wiki sites, you name and fill out sections. The page's TOC is automatically generated, based on the sections (so it's a one-level hiearchy). The reader then clicks a link in the TOC to jump down to a specific section.

Well we've debated about that. Maybe adding in sections can work, but it can also be time consuming to write individual sections or to paste in your 30-page document into 54 different sections. That might not work out so well.

TechNet Wiki works like a blog... there's only one section that you write or paste content into. It's simple.

So what could we do then? We initially had folks using the Anchor tag feature to tag sections and then link down to those sections. So we had people creating manual TOCs. We still do that some, especially when we want to create interesting horizontal TOCs, like this alphabetical TOC on the Technologies Portal:

From here:

https://social.technet.microsoft.com/wiki/contents/articles/275.aspx

...Or this monthly TOC in the Microsoft Events article:

See it in the article here:

https://social.technet.microsoft.com/wiki/contents/articles/microsoft-events.aspx#Events_of_the_month

Here's one more example of how we created a TOC manually... this one is for the SQL Server Release Notes:

https://social.technet.microsoft.com/wiki/contents/articles/microsoft-sql-server-2008-sp2-release-notes.aspx#Contents

However, we also wanted something that was faster and automatic.

Thanks to Sean Jenkin, John Wood, and others from the TechNet/MSDN team, we created a nifty little [TOC] feature.

You'll see on the front page of the Wiki, that we dropped in a little one-sentence explanation:

Use [toc] in the content of an article to automatically generate a Table of
Contents!

And that's it. It's that simple, really. You just type "[toc]" anywhere in your article (in the Design tab; you don't have to be in the HTML tab). Then it takes all your headers and creates a TOC.

Many articles have one, such as this article, "XNA Content Pipeline Overview":

https://social.technet.microsoft.com/wiki/contents/articles/xna-content-pipeline-overview.aspx

Specifically, your headers automatically build out <a name=example></a> tags into the HTML, and the TOC feature uses those tags along with header number in order to determine the hierarchy in the TOC.

For example, on this article, "Feature Requests for TechNet and MSDN Profiles and Social Platform Tools" (yes, some interesting articles exist on TechNet Wiki), I used Heading 3 headers to create the top sections of each platform tool (such as Wiki, Forums, Blogs, Profiles, and Gallery). Then I used a Heading 2 to make the "Completed/Closed Requests" section at the bottom. Even though it's a higher heading, the H3s were listed first, and so the H2 below them is listed at the same hierarchical level as the H3s (this is a good thing; trust me). Then under my H2 ("Completed/Closed Requests"), I included several H3 sections for each social platform tool. This time, because those H3s were listed below the H2 section, they were indented to the right in the TOC hierarchy:

https://social.technet.microsoft.com/wiki/contents/articles/feature-requests-for-technet-and-msdn-profiles-and-social-platform-tools.aspx

So it's a fantastic and smart system! And that's one advantage of the TechNet Wiki TOC... you can easily control the hierarchy and how many levels you want!

And finally, what would a Wiki be if we didn't explain how to use this wonderful tool in a Wiki article?

https://i1.social.s-msft.com/Profile/u/avatar.jpg?displayName=Peter%20Geelen&size=extralarge&version=b0dca935-9e33-49d7-a97f-1f37630d43e8

Peter Geelen created this great Wiki article called, "How to Automatically Add a Table of Contents (TOC) to Your Wiki Article" here...

https://social.technet.microsoft.com/wiki/contents/articles/3329.aspx

And now I think I'll use what I wrote for this blog post to add a section about how the headers determine the TOC hierarchy! That's the way the Wiki works... it's organic and collaborative.

Now that we introduced you to social content authoring...

You'll never want to go back to selfish authoring again!

 

Oh, wait, this isn't you yet? Then we haven't properly introduced you! Come on in, the wiki is fine!

www.technet.com/wiki

 

- Ninja Ed (Blog, Twitter, Wiki, Profile)

Comments