Principles (TODO)

The most common questions asked about a documentation system are:

• Does a document exist for my needs?
• If so, how to I find it?
• Is this document the latest version?
• Is this document still relevant?
• Is this document complete?
• Are there other related documents?
• Who changed this document?
• What were those changes?
• How do I go about fixing an obvious mistake?

Wikis tend to solve these problems.

Understand these general principles:

• A Wiki differs from other types of folder-based documentation strategies such as SharePoint and shared folders in that its philosophy is High Freedom; High Visibility; High Recovery. Anyone can create a page, but not anonymously, and any mistake can be easily undone - by anyone.
• Azure DevOps Wiki allows you to see the history of just the changes that everyone has ever made to a page.
• Pages can be organized into a top-down tree-structured hierarchy to group similar pages together; but...
• Users will more than likely start with the search bar to find a page - a bottom-up strategy. So make ensure you have good KEYWORDS and context to be able to find your page.
• There are many ways to organize a set into a tree because things have more than one category; e.g. color, size, shape, etc. Only one can category be used to define a tree so make your choice. There will always be people who would choose differently, so make sure the bottom-up search approach is always a sufficient method to find a page.
• The hierarchy is often good for new readers who wish to ramp up and don't necessarily know where to start. A hierarchy can give a book-like sequential structure or outline to follow and group related pages together under some topic. This is why our wiki is often structured with parents representing:
  • Applications
  • Concepts; e.g. Banner Standards, Best Practices
  • Proposals
  • How To's
  • Teams
  • Processes
• Linking between pages should include the entire URL, which contains the permalink Id (the /NUMBER/ part), so that if a page is moved, the link does not break. Everything on the URL that follows the permalink is ignored.