Best practices for a Wiki/Glossary among several projects

Question

We're using Confluence to share our knowledge about several Projects.

This also includes noting the growing know-how related to working on growing Code and Repositories.

By the time and commitment of several programmers there's quite an output over time. What are your strategies and best-practices to keep Glossaries readable and update-able?

And how do you structure your Index- and Wiki-Pages and ares so people are able to find what they are looking for as afford-less as possible?

Especially related to common bugs it would be nice to keep it StackOverflow-Like and avoid parallel or overlapping Index-Pages.

Can you tell me a bit about your ideas and solutions?

Thank you

Robert Reiner _smartics_ · Answer

It seems to me that you have some quite concrete use cases in mind (glossary, bugs, StackOverflow-like application), but since you are also asking for ideas, you may also be interested in some more general information. So I'm not sure if I understand the context of your question correctly.

I'll give it a try by focusing on the "readable and update-able" part.

Organization:

TL;DR: Define information architecture, have people in charge to support writers

A wiki often quickly becomes a mess if nobody has created a basic information architecture. This includes answers to question like which information is relevant and which blueprints could support writers to provide this information in a uniform manner. But also which labels (or other metadata) should we use and what are their meanings. This is a quite crude description. You'll find more on this topic in Information Architecture for the World Wide Web (there is also an updated version of this book).

If the information architecture (or whatever part of that is sufficient to get your team started) is defined (including a style guide and glossary), you would need some gardeners who take the responsibility to help writers to add their information in the shared wiki spaces. A wiki is a living creature and needs to be taken care of. There are new ideas, insights, or simply new requirements that demand changes. These changes often require an amount of work that cannot be integrated into the daily routines.

I have recently watched an interesting videocast by Beth Aitman on Supporting non-writers to write effective content. She describes how she provides support to developers to write technical documentation.

Practices:

TL;DR: One location for each document type, use dynamic lists and transclusion

We have complied a list of (values, principles, and) practices of agile documentation on our website. The following list contains ideas that I think are directly linked to your question:

* The location of a new wiki page should be based on invariant information. Otherwise it will get difficult to determine where to create a new page. There is very few invariant information like creation date, creation author, and type of document. We use the document type. There are rules as when a page should be a subpage, but I do not want to get too detailed here.
* If you have many pages piled up in one place, you'll need metadata to create multiple views on these documents. These views support browsing. Dynamic links / dynamic lists ensure that the link lists are not manually crafted. Macros like the Content By Label Macro allow to collect links to pages with the same label automatically. A new page simply shows up dependent on its labels. Having more dimensions than just labels often is very useful.
* Transclusion (e.g. with the Excerpt Macro) is important to reuse information and supports single sourcing. Keeping the documentation modular is generally a good idea (one page = one topic). But this is more difficult than it sounds and you probably need a third party tool to use multi-excerpts.
* Regarding the granularity of spaces – as a basic organization of information – there is a discussion on this forum: How Granular are your Spaces?

As stated above, I hope I could give some hints on our view on information management with Confluence. If I'm not exactly hitting your problem, maybe you could give some examples on what are your main concerns. You are hinting on Index pages. If the "one location thing" does not meet your requirements, maybe you could give some more examples describing the problem you are facing?