Principles around creating a document repository

manager Wed, 11/06/2019 - 19:21

Summary

Documentation is about the content not the tool, that said there are some basic requirements for a tool.

  1. The tool should not have much of a learning curve, it should be easy to use to add and edit content, the older tools that require learning a markdown language should be avoided in favor of tools that support WYSIWYG editing.
  2. The tool should have good support for full-text search
  3. The tools should make it easy to relate or network content, one good example is the book where you can add child pages to any existing page.
  4. The access should be wide open, teams don't have private data, with the exception of credentials that should be stored in a password manager.
  5. It is desirable for the tool to have revision control, the benefit of this is we can allow the crowd sourcing model for information, without concerns if someone adds incorrect information.
  6. The tool should support easy use of images, images should include links to the original document used to create them so they can be updated.

To avoid out of date information, it should be easy for anyone at any time to say this is wrong or out of date, let me just correct it right now.

While it is desirable to have one place to go to search for all information, It is usually not a good idea to try a force a migration all existing documentation if the data set is larger than can be moved quickly.  This is because what often happens is the migration runs out of gas before it is complete. Insted it is better to take what I call the umbrella approach where you have an index with pointers or references for key search terms and topics that point to the existing document repositories.

Priority should be given to documentation that will be most useful.  These often means conceptual documentation at a higher level that would be useful to provide context to many people, is preferable to low level implementation details that few people would need to know or that might change often.

For low level implementation specific documentation it is better to automate the generation of that documentation because it would be too time consuming to maintain it.

Tips for a better Wiki 

  1. Invite users to participate by editing and commenting on the content
  2. Don’t overthink it, just do it
  3. Remind users to use the built-in wiki search
  4. Integrate your wiki with in-house databases
  5. Implement a wiki within those groups or departments that have immediate use for it. Forcing the wiki as a company-wide mandate is usually not a good idea.

Traditional Wiki

A wiki is software that allows users to create, edit, and link web pages easily. Wikis are often used to create collaborative websites and to power community websites. They are being installed by businesses to provide affordable and effective Intranets and for Knowledge Management.

  1. All organizations use jargon and acronyms; we assume that everyone knows what they mean. *Establishing a corporate dictionary for naming standards and term definitions.
  2. Data tier definitions and defining consistent data descriptions.
  3. Repository user manuals, user guides and best-practice documentation.
  4. Defining and describing data standards, meta-models and enterprise structures.
  5. The basic difference with the wiki-based approach versus the traditional command-and-control model is the collaborative nature.
  6. A wiki is meant to represent the collective knowledge of many people about a subject. You are free to contribute additional information. You can view a history of edits to any page by clicking this history. Pages may be watched by those interested in tracking changes.
  7. The difference between a Blog and a Wiki is a blog will contain a single person’s opinion and is not collaborative in nature.

Ward Cunningham, developer of the first wiki, WikiWikiWeb, originally described it as "the simplest online database that could possibly work". One of the best known wikis is Wikipedia.

Navigation

Within the text of most pages there are usually a large number of hypertext links to other pages. This form of non-linear navigation is more "native" to wiki than structured/formalized navigation schemes. That said, users can also create any number of index or table of contents pages, with hierarchical categorization or whatever form of organization they like. These may be challenging to maintain by hand, as multiple authors create and delete pages in an ad hoc manner. Wikis generally provide one or more ways to categorize or tag pages, to support the maintenance of such index pages.

Most wikis have a backlink feature, an easy way to see what pages link to the page you're currently on.

It is typical in a wiki to create links to pages that do not yet exist, as a way to invite others to share what they know about a subject new to the wiki.

Linking and creating pages

Links are created using a specific syntax, the so-called "link pattern" (also see CURIE).

Originally, most wikis used CamelCase to name pages and create links. These are produced by capitalizing words in a phrase and removing the spaces between them (the word "CamelCase" is itself an example). While CamelCase makes linking very easy, it also leads to links which are written in a form that deviates from the standard spelling. CamelCase-based wikis are instantly recognizable because they have many links with names such as "TableOfContents" and "BeginnerQuestions". It is possible for a wiki to render the visible anchor for such links "pretty" by reinserting spaces, and possibly also reverting to lower case. However, this reprocessing of the link to improve the readability of the anchor is limited by the loss of capitalization information caused by CamelCase reversal. For example, "RichardWagner" should be rendered as "Richard Wagner", whereas "PopularMusic" should be rendered as "popular music". There is no easy way to determine which capital letters should remain capitalized. As a result, many wikis now have "free linking" using brackets, and some disable CamelCase by default.

Searching

Most wikis offer at least a title search, and sometimes a full-text search. The scalability of the search depends on whether the wiki engine uses a database. Indexed database access is necessary for high speed searches on large wikis. Alternatively, external search engines such as Google can sometimes be used on wikis with limited searching functions in order to obtain more precise results. However, a search engine's indexes can be very out of date (days, weeks or months) for many websites.

Trust and security

Controlling changes

Wikis are generally designed with the philosophy of making it easy to correct mistakes, rather than making it difficult to make them. Thus, while wikis are very open, they provide a means to verify the validity of recent additions to the body of pages. The most prominent, on almost every wiki, is the "Recent Changes" page—a specific list numbering recent edits, or a list of all the edits made within a given time frame.[7] Some wikis can filter the list to remove minor edits and edits made by automatic importing scripts ("bots").[7]

From the change log, other functions are accessible in most wikis: the Revision History showing previous page versions; and the diff feature, highlighting the changes between two revisions. Using the Revision History, an editor can view and restore a previous version of the article. The diff feature can be used to decide whether or not this is necessary. A regular wiki user can view the diff of an edit listed on the "Recent Changes" page and, if it is an unacceptable edit, consult the history, restoring a previous revision; this process is more or less streamlined, depending on the wiki software used.[7]

In case unacceptable edits are missed on the "Recent Changes" page, some wiki engines provide additional content control. It can be monitored to ensure that a page, or a set of pages, keeps its quality. A person willing to maintain pages will be warned of modifications to the pages, allowing him or her to verify the validity of new editions quickly.

Trustworthiness

Critics of publicly-editable wiki systems argue that these systems could be easily tampered with; while proponents argue that the community of users can catch malicious content and correct it.[2] Lars Aronsson, a data systems specialist, summarizes the controversy as follows: “ Most people, when they first learn about the wiki concept, assume that a website that can be edited by anybody would soon be rendered useless by destructive input. It sounds like offering free spray cans next to a grey concrete wall. The only likely outcome would be ugly graffiti and simple tagging, and many artistic efforts would not be long lived. Still, it seems to work very well.

Security

The open philosophy of most wikis, allowing anyone to edit content, does not ensure that all editors are well-meaning. Vandalism can be a major problem. In larger wiki sites, such as those run by the Wikimedia Foundation, vandalism can go unnoticed for a period of time. Wikis by their very nature are susceptible to intentional disruption, known as "trolling". Wikis tend to take a soft security[9] approach to the problem of vandalism; making damage easy to undo rather than attempting to prevent damage. Larger wikis often employ sophisticated methods, such as bots that automatically identify and revert vandalism and JavaScript enhancements that show how many characters have been added in each edit. In this way vandalism can be limited to just "minor vandalism" or "sneaky vandalism", where the characters added/eliminated are so few that bots do not identify them and users do not pay much attention to them.

The amount of vandalism a wiki receives depends on how open the wiki is. For instance, some wikis allow unregistered users, identified by their IP addresses, to edit content, whilst others limit this function to just registered users. What most wikis do is allow IP editing, but privilege registered users with some extra functions to lend them a hand in editing; on most wikis, becoming a registered user is very simple and can be done in seconds, but detains the user from using the new editing functions until either some time passes, as in the English Wikipedia, where registered users must wait for three days after creating an account in order to gain access to the new tool, or until several constructive edits have been made in order to prove the user's trustworthiness and usefulness on the system, as in the Portuguese Wikipedia, where users require at least 15 constructive edits before authorization to use the added tools. Basically, "closed up" wikis are more secure and reliable but grow slowly, whilst more open wikis grow at a steady rate but result in being an easy target for vandalism. A clear example of this would be that of Wikipedia and Citizendium. The first is extremely open, allowing anyone with a computer and internet access to edit it, making it grow rapidly, whilst the latter requires the users' real name and a biography of themselves, affecting the growth of the wiki but creating an almost "vandalism-free" ambiance.

Wiki communities

Many wiki communities are private, particularly within enterprises. They are often used as internal documentation for in-house systems and applications. The "open to everyone", all-encompassing nature of Wikipedia is a significant factor in its growth, while many other wikis are highly specialized.

There also exist WikiNodes which are pages on wikis that describe related wikis. They are usually organized as neighbors and delegates. A neighbor wiki is simply a wiki that may discuss similar content or may otherwise be of interest. A delegate wiki is a wiki that agrees to have certain content delegated to that wiki.

One way of finding a wiki on a specific subject is to follow the wiki-node network from wiki to wiki; another is to take a Wiki "bus tour," for example: Wikipedia's Tour Bus Stop. Domain names containing "wiki" are growing in popularity to support specific niches.

For those interested in creating their own wiki, there are many publicly available "wiki farms", some of which can also make private, password-protected wikis. PeanutButterWiki, Socialtext, Wetpaint, and Wikia are popular examples of such services. For more information, see List of wiki farms. Note that free wiki farms generally contain advertising on every page. For those interested in how to build a successful wiki community, and encourage wiki use, Wikipatterns is a guide to the stages of wiki adoption and a collection of community-building and content-building strategies.

The English-language Wikipedia has the largest user base among all wikis[10] and ranks in the top twenty among all websites in terms of traffic.[11] Other large wikis include the WikiWikiWeb, Memory Alpha, Wikitravel, World66 and Susning.nu, a Swedish-language knowledge base. The largest wikis are listed and updated on Wikimedia's "meta" wiki.

Wikis and content management systems

Wikis have shared and encouraged several features with generalized content management systems (CMS), which are used by enterprises and communities-of-practice. Those looking to compare a CMS with an enterprise wiki should consider these basic features:

  1. The name of an article is embedded in the hyperlink.
  2. Articles can be created or edited at anytime by anyone (with certain limitations for protected articles).
  3. Articles are editable through the web browser.
  4. Each article provides one-click access to the history/versioning page, which also supports version differencing ("diff") and retrieving prior versions.
  5. The most recent additions/modifications of articles can be monitored actively or passively.
  6. Easy revert of changes is possible.

None of these are particular to a wiki, and some have developed independently. Still the concept of a wiki unequivocally refers to this core set of features. Taken together, they fit the generative nature of the Internet, in encouraging each user to help build it.[12] It is yet to be studied whether an enterprise wiki encourages more usage, or leads to more knowledgeable community members, than other content management systems.

Wiki Standards

In an attempt to provide a central location for recommended practices, here is the Wiki Standards page. Please offer/glean best practices to assist in creating the best wiki environment possible.

Thoughts on Best Practices

A defining characteristic of wiki technology is the ease with which pages can be created and updated. A wiki enables documents to be written collaboratively, in a simple markup language using a web browser. A single page in a wiki is referred to as a "wiki page", while the entire collection of pages, which are usually well interconnected by hyperlinks, is "the wiki". A wiki is essentially a database for creating, browsing, and searching through information. Our standards are complemented by our Wiki Strategy.

Article Structure

Choose the name of a new article carefully, this will become the name of the link to this page. Generally the article name will be in the singular form i.e. Department not Departments. The most important structure for a page is to include hypertext links. This means adding internal links around words in the article. This promotes the networking of information on the wiki.

Summary of the page

This is a sentence or two to summarize what is on the page, this should appear before the first section heading.

Headings for sections

These are the headings and sub headings for the article content.

See Also (Related Content)

Our internal wiki will group related articles with category assignments. To see pages in the same category click on the category links at the bottom of the page. We will also have a related content section at the bottom of the article right before the External Links Section Wikipedia articles tend to have a See Also section near the top of most articles followed by the information forming the article itself. While this doesn't necessarily produce a direct parent child relationship, it does provide a hierarchy of sorts and enables easier navigation.