About Documentation

I believe that the crucial element in creating a good documentation system is a "single entry" concept.

Materials can be shared between different services like cloud, sharepoint, charts, videohostings but there should be one place that guides users to all of them. Like home page of www.aredel.com guides through all content of the website.

One Portal to Rule them all One Portal to find them One Portal to Bring them all and to the Wiki Bind them Lord ot the Docs

For companies it is more difficult to maintain custom system like this website.

They tend to use popular sofware systems which could be designed to be documentation hostings or could be just some file storages.

If they manage to stick with a single tool it is already half of success. Even if the tool is mediocre.

In real life companies tend to keep training materials, specifications, documentation, videos in various dedicated sytems. It is not aligned with my concept of a single entry and I will try to reveal the drawbacks of such approach.

If we talk about software developers they do not usually store part of their code in github, other part in gitlab and remaining part in bitbucket. But since documentation usually is not a plain text but is either text or video or pdf/presentation etc. people tend to think it can be stored wherever it fits.

We should consider documentation as a content regardless of it's format. We need to stop separating docs by the content type when it is related to searching and record keeping.

Google is aware of single entry concept for many years and provides both videos and text articles on the same search result page.

Why don't we learn this good practice from them.

If user has to search in multiple systems his efficiency drops significantly with any extra system added.

Besides the fact that more time is waster at some point user can just give up searching for better answer an use whatever is "findable".

Do you really want "findable" answers for your company?

That is why there is a need for a single place that "overlooks" all other sources. From user perspective it is an entry point for any interaction with the docs. The entry point could be any system: custom website, wiki, github, some sharepoint page.

The success mostly depends not on the system itself but on "crowd sourcing".

By crowd sourcing I mean two options:

• There is a process when everybody contributes
• There is a Product Owner for docs and everybody informs him about updates or there is a tool to monitor them.

It is not that difficult to monitor all the new documentation created in your company.

Even if you are Facebook there is a countable number of contributors and hopefully even smaller number of systems into which they can contribute to.

The motivation for updating the "entry point" should be clearly explained to everybody. Motivation is important, "crowd sourcing" is important as well.

When starting working with docs every manager should keep in mind that as Daniel Pink highlighted years ago Wikipedia is still here an Encarta is no more.

Pink's quote from TED talk:

In the mid-1990’s Microsoft started an encyclopedia called Encarta.

• They employed all the right incentives.
• They paid professionals to write and edit thousands of articles.
• Well compensated managers oversaw the whole thing to make sure it came in on budget and on time.

A few years later another encyclopedia started — A different model

• Do it for fun.
• No one gets paid a cent or a euro or a yen.
• Do it because you like to do it.

Now 10 years ago* if you had talked to an economist … anywhere … and said

“Hey, I’ve got these different models for creating an encyclopedia — If they went head to head who would win?

10 years ago* you could not have found a single, sober economist anywhere on planet earth who would have predicted the Wikipedia model. This is the Titanic battle between these two approaches.

This is the Ali-Frazier of motivation, right, this is the Thrilla in Manila, alright — Intrinsic motivators vs extrinsic motivators — Autonomy, Mastery & Purpose versus Carrots & sticks – And who wins — Intrinsic motivation, autonomy, mastery and purpose — in a Knockout.

End of quote.

Pink's TED talk on YouTube

Pink's TED talk was in 2010.