Wiki Information Architecture

From Artisans Asylum Wiki

These are the concepts and guiding principles behind the information architecture of this wiki. This information architecture and philosophy was developed and refined by the A2 wiki working group from Q3 2023 through Q2 2024, and it's based on tons of existing research and work in the fields of technical writing, library science, and content management (see the list of references at the end of this page).

Put information in the right place

Generally, information should be stored online where most people look for it and where the platform (software) supports the way in which this information is being used. For example, it makes little sense to have a real-time conversation with another person online by using a series of static web pages. Similarly, you wouldn't expect someone in a Discord chat to rattle off a detailed list of all of the possible speeds and feeds to use when drilling a hole using a milling machine; instead, this information is better represented as a reference chart (or even a software calculator).

Use this chart of What Information Goes Where at A2 to determine if your content is best stored on the wiki, or it makes more sense to use a different platform.

Some corollary ideas:

  • If you can't find something, it might as well not exist
  • If something is hard to find, rework it or recategorize it instead of destroying it and rebuilding from scratch
  • Don't put the same information in multiple places -- instead, link to one authoritative source of truth
  • Think like a beginner -- how would a newbie look for something? How would they understand what you wrote?

Structure pages clearly and consistently

After you've figured out that the wiki is a great place for your information, consider, broadly speaking, what type of wiki page ("topic") this will be. Avoid the temptation to mix content types on a single wiki page, or to write every topic using the same content type. Someone who is looking for information on the wiki is trying to find out what they want to know, fast! If you organize your page using these categories, you will save your reader from wading through unnecessary cruft to get what information they need.

Broadly speaking, your topic should fall into one of three general types -- Concept, Task, or Reference.

Concept

A Concept topic provides answers to every important WHAT or WHY related to the topic. Concept topics should answer questions like:

  • What is this idea all about, anyway?
  • What's the fundamental philosophy about this?
  • How did it come to be this way?

This page that you are reading is a concept topic; see the Concept category for examples and descriptions of how to write concept topics effectively.

Task

A Task topic helps to find answers about every HOW to related to the subject of the topic. Task topics should answer questions like:

  • What is the best way to get this done?
  • How do I perform this task safely and efficiently?
  • What materials might I need to get this work done?
  • What are the exact steps I need to take to do this work?

The goal of a task is to help the reader accomplish something by providing step-by-step instructions. This can be really difficult to do! If you are writing about how to do something, you're probably already an expert on it, and you might not remember what someone else might need to know in order to accomplish a task that is second nature to you. The Task category has examples and suggestions about how to write effective task documentation.

Reference

A Reference topic helps to find answers about WHICH additional information the users need to know about the subject. Reference topics should answer questions like:

  • What are all the committees at Artisan's?
  • What settings should I use on the lasercutter to etch, depending on which material I have?
  • What materials can I cut in the wood shop?
  • What parts does the electronics and robotics shop have in inventory?

If you are an expert, and you're trying to write a document that helps the reader, carefully consider whether or not to use this content type or to write a task document instead. It's often easy to make a list of all the things you know -- and you probably know a lot of things -- but most people are trying to perform some kind of meaningful work, which means that they want to know the best way to do something, not all of the awesome capabilities of the tool, fabrication process, or subject matter that you're writing about.

Categorize pages

The most visible element of the wiki's information architecture is the category system. Each page should be tagged with at least one category (Concept, Task, or Reference) and usually an additional category that is specific to Artisan's. By way of example, here are some specific categories we've created for use on this wiki:

You can see a comprehensive list of all the categories on this wiki here. If you think your wiki page belongs in a new category, consider first whether this category will only have one page (yours) or lots of pages. If you see a need to collect lots of pages into a new category, go for it! Make your category and then tag every relevant page with that category type. A page can have multiple categories.

Templates

If your page has an Artisan's-specific category, there's a pretty good chance that there's also a template that you can use to structure some of the information on your page. For example, all tools have a manufacturer, photograph, shop that they're located in, and tool restriction. Furthermore, most tools have manuals. Use the ToolBox Template on your tool page to easily display and format this common information, so that the reader can scan visually over to the spot on the page where this information is usually found.

Tool categories

Take extra care to figure out if a tool page should be a category page or not. For example, we have lots of band saws at Artisan's. They all require the same PPE and have similar hazards. Put all this common information on the Band Saws category page, and move the tool-specific information, like the make, model, and link to the manual, to a separate page with a title that is specific to the band saw you're documenting.

Write simply and clearly

Keep it simple. Don't use complex terms when simple ones will do. Don't make it harder for your reader to decode your writing by using jargon, idiomatic phrases, or superfluous language. Follow the style guide we've created and you'll be well on your way to creating awesomely helpful content. Have someone review your work before you publish it on the wiki -- that additional review will make a huge difference in the quality of your writing.

References and further reading

Retrieved from "http://wiki.artisansasylum.com/index.php?title=Wiki_Information_Architecture&oldid=3475"