Wikis are different from other kinds of electronic documents. Here are some ways to use those differences to your advantage.
First, let's look at a what a wiki is not.
A wiki is not a book.
Books are prepared at all once and then published. It's important to have everything correct at the time of publication, because you can't go back and fix something. With most books, a strict linear reading order is recommended. With any book, it's difficult for the reader to make their own changes or edits.
A wiki is not a set of papers.
Like books, papers are meant to be complete and then published. Shared folders and cloud systems have made it possible to update papers, but they're not linked to each other. With folders or papers in email, there's no navigation system or table of contents to guide your users.
A wiki is quick way to record facts, even as they change.
It's easy to add things, edit them, or move them around later.
People might read the wiki in any order.
They can contribute their own pages and edits anytime.
- Great Navigation
- A Simple Home Page
- Links Where They Make Sense
- Special Formatting
- Media & Documents
- As you develop content, take time to revise your navigation to bring the most important sections and links forward.
- Use icons to add visual interest and differention between your links.
- Use a limited number of headers to group links together.
- As your content grows, think about creating section pages or "landing pages" with deeper links.
- As your wiki changes, update your home page to bring the most important sections and pages front-and-center.
- Use images and branding elements on your home page so users know they're in the right place.
- Consider adding a What's New section in an infobox to show what you've changed.
- Use links to other pages in your wiki when there is deeper content at the link for the user to explore.
- Don't repeat links to simpler or "parent level" content from within deeper topics.
- Start section or landing pages with a formatted list of the most important pages in the section.
- Use multiple lists to group links rather than putting all links together.
- Consider creating a related Quick Links section and use it repeatedly at the top of deep topic pages.
- Most special formatting codes can be reached by selecting some text, then using the formatting toolbar.
- Use special formatting when it adds information to your writing.
- Don't use special formatting if it distracts from writing your text. Add it later.
- Use headers in numerical order to create an automatic table of contents for your page.
- Try to use bold and italic consistently to mean only one thing each.
- Use automatically numbered lists for things that happen in order.
- Use a bulleted list when the order doesn't matter.
back-quote syntax to quote examples from your product or user interface.
- Use the Keyboard syntax to show buttons that users should press.
- Use icons when they relate to your product.
- Use code blocks to show complex syntax or instructions and enable block copy and paste:
- A good wiki should include links to documents outside the wiki.
- Use navigation and landing page design to make outside documents easy to find.
- Choose names for outside documents that make sense inside the wiki.
- Consider using lists to organize documents from other sources into better groups.
- Use headers and other special formatting to make it easy to find important documents.
- Add pictures, video, and audio files to your pages when they add information.
- Consider drawing diagrams in a tool that supports SVG output. These scale automatically.
You can and should edit the wiki, especially when you find errors that you can fix.
When there's information to add that could be helpful to others, just add it!
Of course, these suggestions depend on the organization's policies and how you setup your wiki.
But, in general, its best to include as many team members as possible in the editing process. In practice, people are hesitant to write or edit anything unless they are confident it's correct. This helps you fix a lot of common typos, incorrect facts, and other problems that are natural with any kind of electronic document.
- Encourage your users to make edits by adding links to our documentation and Masterclass videos.
- Give wide permissions for editing within your organization.
- Give users enough structure in the navigation to know where to add things.