Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal

Recognition

  • Give kudos
  • Received
  • Given

Leaderboard

  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage
Highlighted

Best practices for a Wiki/Glossary among several projects

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

1 comment

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?

Like Rufus Casey likes this

Comment

Log in or Sign up to comment
TAGS
Community showcase
Posted in Confluence

What do you think is the most *delightful* Confluence feature? Comment for a prize!

- Create your own custom emoji 🔥 - "Shake for Feedback" on mobile 📱 - An endless supply of GIFs via GIPHY 🤩 Is there anything quite as nice as a pleasant surprise? Comment below with what...

463 views 24 9
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you