Medic! We need a Wiki Ninja medic! … The dissection of the ideal TNWiki article.


When you're publishing articles to TechNet Wiki, you'll see some cases where the content you want to publish doesn't seem to display the way you like.

On the TechNet Wiki and on this blog you'll find plenty of hints and tips with guidance to publish.

In this article we'll deep dive into some Wiki internals to explain how you can get the results you like to have.

And more important to KEEP it the way you LIKE IT, avoiding future edits to ruin your patient.

So put on your rubber gloves, get everybody out of the room, because we're going down to the dissection of the ideal Wiki article, including the bloody details.

Mind the system, respect the old lady.

What do you mean "mind the system"??

When you publish articles, the content is being evaluated against some common threats and unsupported features.
Most famous check is advanced layout, complex CSS features and scripts.

You'll notice that the engine strips certain parts of your article or unsupported HTML code.
Some of the scripts can harm the system, so there's an obvious reason to strip certain code.
Live with it and keep breathing.

And as we know the TechNet Wiki has some caveats.. (Documented over here.)

In some case, you can't change it, in some other cases you can use alternatives.
So keep out of the way of these known issues, it will make you're life easier.

That's exactly what I'm going to cover in this article.

The good news: in a few weeks Wiki is migrated to a next generation platform, count down has started...

HTML

Did you ever check tha HTML content of your article, did ya?

There is a very simple rule of thumb: if your HMTL code is as simple as the layout of your article, you're good!

What I mean is: the more complex, redundant, overloaded HTML you got, the worse the performance of your article... (slow load times, broken links, slow save times, TNWiki engine issues...)

KISS

No, not the physical thing.

KEEP IT SIMPLE AND ehh.....

Simple layout, basic default fonts, easy structure, ... will GREATLY improve readability.

Resist to the urge to make it fancy and complex. Enjoy simplicity.

The famous <br> tag issue

One of the current issues with the TNWiki (no actually it's TNWiki vs some browsers) is the <br> HTML tag.

Some edits will simply duplicate the <br> tag, resulting in a pretty messed-up article when you hit the Edit button.

SIMPLE FIX: replace ALL <br> tags with a reversed paragraph tag: <br> becomes </p><p>

 

Font layouts

A very simple advice: do NOT use any special fonts, font sizes, special spacing, font-heights, line-height.

USE SIMPLE HEADERS to put sections in your Wiki Article.

DO NOT replace headers with any variation of font-sizes, for the simple reason that you won't be able to use the [TOC], at all.

This also applies to copy/paste from any dummy HTML editor (you know some of these nice editors to create OFFLINE documents ARE NOT fit to write HTML online documentation).

Some of the offline editors have the nasty habit to dump FAULTY, redundant, overloaded HTML.

Color names

Medic Ninja Richard Mueller has dissected the issue here: http://social.technet.microsoft.com/wiki/contents/articles/16870.wiki-fix-color-issues-in-wiki-articles.aspx.

Replace any color codes (RGB, HEX, ...) to color names.

You'll notice that the articles greatly benefit from using COLOR NAMES.

Additional advices, minimize the color variations to a strict minimum.

More info: http://social.technet.microsoft.com/wiki/contents/articles/18674.using-powershell-to-fix-rgb-codes-to-rgb-names-in-your-html-code.aspx

Personalization

One of the major advantages of TNWiki is also a major disadvantage, it's open to anyone.

TNWiki is a community, and one of the basic rules if you publish to TNWiki: you are the initial publisher, you get the credits. But you DO NOT OWN the content. The community does.

The TNWIki is NOT YOUR PERSONAL BLOG. (PERIOD!)

So, personal stories ("Hello everybody,  I'am ... and I like ... and I think ...) do NOT belong to TNWiki.

Idem for personal signatures in an article. [OUT!]

Need more info? Look at : https://aka.ms/wikipersonalization and https://aka.ms/NotForTNWiki).

Tip: write an technical article fit for TNWiki so that the community can contribute and improve your article.

Good news: you'll get the credits for it too!

External pictures

Another typical disease that TNWIki articles suffer from are embedded images with links to 3rd party platforms.

You'll quickly notice that this kind of patient will have performance issues, load slowly or will not show the images anymore.

Golden rule: upload the images natively to TNWiki and keep them shining.

Meaningful edits

Some of the edits (like the <br> tag issue I mentioned), are not visible in the article history. That's a fact.

But you will NOT get any credits for just cleaning up some blank spaces.

And people get annoyed by it, so you risk to get in a fight.

So here's the simple advice:

  • do meaningful edits only
  • change or add tags if meaningful
  • do more than one change at a time
  • clean up thoroughly (clean redundant HTML, remove personalization, add [TOC], add headers ,... clean fonts, ...)

EASY!

You now got more than enough guidelines from this article, right?

Tags

One of the WORST used TNWiki features are tags.

A while ago, I made a calculation of the tag statistics...

And more than 90% of the tags are only used ONCE. This is completely [beep... eh ... beep ... beep]

Be smart, use smart tags, which means:

  • short tags, one word - two word tags
  • reuse tags
  • rather use multiple tags than one meaningless single use tag.
  • ...

I've elaborated on this topic before on this blog:  » Wiki life: Technet Wiki tagging, the ugly truth.

 

Piracy, privacy, kittycat-copycat

I don't want to dive into the legal part of it. You know how it works.

Hard core pirates will not take time to write an article with their own content...

But when you dissect an article with suspected piracy, it becomes very simple.

Majority of pirated articles contain the source code or the original content, so you flag yourself as a pirate very easily.

We got some very good Wiki ninjas with a fine nose for pirated content detection! (And I'm getting good at it too!)

BUSTED! Don't be surprised if you get your [#@] kicked.

The nice advice: be original, write it yourself, FROM SCRATCH.

We DO appreciate your own content, even if it's not perfect (yet).

The quick procedure for HTML cleanup

So below (roughly), is the typical process when I'm conditioning an article (without any coloured source code).

Few additional, more complex edits are missing, but this should do as a start:

  1. Go into Edit mode
  2. Clean the code using the Format stripper
    1. this is a very good exercise to detect how much redundant HTML you have
  3. Go to HTML mode
  4. Copy the HTML in an offline editor like Microsoft Expression web (FOR FREE)
  5. Clean all double spaces (it will simplify next steps)
    1. replace double space with single space
    2. repeat until none left
  6. Add a <p> tag at the beginning of the article and replace all <br> with </p><p> (yes, a reverse <p> tag combination) 
  7. Add a horizontal line <hr> to the very last end of the article
  8. Make sure your headers start with H1, then H2, next H3, ....
    1. Do NOT use any fancy layout to mark headers : it will damage your TOC
    2. Do no use large size fonts, special fonts, ... (In short: NO FONT layout, font-family, font-size, font- eh... what ever,  remove it.)
  9. Add a <hr> just before any H1 header
  10. Add a "Back to Top" reference before major headers (Read this: https://aka.ms/returntotop)
  11. Mark source code between <code> ... </code> tags
  12. Replace RGB/HEX color codes with color names
  13. If there are multiple chapters with headers: add the [TOC]
  14. Remove personalization

So this should give you some insights to join me on improving the TNWiki content, and to make it a great community resource!

[Ka-jah Shakaah!]
The Security & Identity Ninja, taking care of TNWiki Governance.

Peter Geelen     

Follow me on Twitter: https://twitter.com/geelenp 

Comments (13)

  1. Excellent article Peter!

    If I can add another point, use Firefox for editing your wiki pages. I had no end of problems with both IE and Chrome but Firefox formats things nicely. It also prevents a lot of the extra spacing issues mentioned above.

  2. Saeid Hasani says:

    So much helpful!
    Thanks Pete for the fantastic post!

  3. Medic! Peter is definitely our medic. Thanks for the tips!

  4. Andy ONeill says:

    Great post Peter.

    Some people get focussed on racking up stats. People notice when you make the same trivial edit to many articles. Some get very annoyed.

    I expect the break tag thing will be going away when we migrate to the new platform.

  5. Excellent post Peter. @Andy, i think you need to put those comments to side now. Dissing people without having the actual guts to ask a direct question and to firstly understand what is going on, i think you need to focus on that. You know what I mean.
    This is becoming a tiresome exercise and honestly people are also getting tired of the comments you posting about other people. That said, if you have an issue with someone because you don’t know whats going on, ask first. Dont stand out like a sore thumb
    to look like the good person. Enough said.

  6. Chervine says:

    Great post! Thanks for the tips!

  7. Durval Ramos says:

    Peter, Great tips!!!

    Definitely, Peter’s the doctor on TNWiki

  8. Anonymous says:

    In my previous article ( Medic! We need a Wiki Ninja medic! … The dissection of the ideal TNWiki article

  9. Danish Islam says:

    Very helpful guide. Thanks for sharing.

  10. John Naguib says:

    Thanks for the guide

  11. anonymouscommenter says:

    Anyone who got sucked into TechNet Wiki and started writing articles, is familiar with the online editor

Skip to main content