Documentation

Introduction of the Single-Entry concept

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 of 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.

Typical Issues with Documentation

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 wasted 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?

Are you willing to pay for inefficient search time?

Searching for documentation should not be painful.

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.

Example

Lets assume that our company stores data in the following places:

• Code in GitHub
• Videos in aredel.com
• Text documentation in urn.su

We have three Suites in our software. Their names are: generators, pytest and robot

How would the single entry documentation look like?

One way to organize it is to make a simple page that lists all Suites.

Will demo it in a text mode so we don't focus on design.

# This is a single entry point to all the docs SEARCH BUTTON generators pytest robot

If user wants to find something about pytest he just clicks it or uses the search button and types "pytest" there

GLOBAL SEARCH BUTTON SEARCH IN PYTEST BUTTON pytest: # here we sort by the content type in case if user is sure that he needs e.g. video code videos text articles Contents: # here we provide content in some logical order regardless of type # order can be by difficulty, by some learning path or anything else # it can be generated for specific need if documentation management system allows it Intro to pytest (this is a link to text article) Simple Example (this is a link to text article) Fixtures (this is a link to video) assertion util (this is a link to github) Parametrization (this is a link to a text article)

Crowd Sourcing

Now when the concept of single entry is clear there comes the need of effective implementation.

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.

Read the Wikipedia vs Encarta chapter to find more about motivation in content creation.

Wikipedia vs Encarta

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.

Daniel Pink's quote from TED talk back in 2010 ( YouTube ):

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.

Creating content that can be found

Organized content + possibility to find as much as possible with search.

Article author: Andrei Olegovich