How do I create a good internal wiki for my team?

People think that hierarchies are the correct way to structure information. In many cases, that makes sense at first. But soon enough, you realize some things don't fit into one place, or there are two or more competing ways of building a hierarchy. At that point people spend a lot of time arguing which hierarchical way of storing documentation is better. You have long conversation about in which folder a document should be housed. You end up with a lot of non-productive conversation.

Forget hierarchies. Build a graph. Create "indices" which link to docs, which link to other docs. Create one or a few places to enter the graph (think the old Yahoo directory). Hyperlink, hyperlink, hyperlink. You can create a hiercharchy if you wish to, and you can also effortlessly structure docs in all other ways. Restructure links as it make sense. More links == more discoverability.

You can do this in pretty much any tool. Wiki. Google Docs. Notion. Quip. etc... If the tool forces you to have a hierarchy of folders, create one, but don't spend ANY time deciding if it is a good one. People will find documents via the links not by traversing the hierarchy.

My two cents: Just do it.

Build/enable integrations with other systems (eg CMDB) so that the wiki can display information from them.

Try to make people feel that they can easily add info to the wiki. An iterative approach is probably suitable – better to add something than nothing. It can then be iterated upon.

Make sure that people feel they have time to add/edit info every week. [Edit: And time to clean out outdated info.]

As others have said, just dive in. If there's no legacy tool in place, getting started is easy -- spin up a docker image of Wiki.js, an instance of MK docs or whatnot, set up a backup methodology and you're off to the races.

The challenge with wikis is always long-haul maintenance and relevance. Information rot and information overload, at scale, can quickly overtake the value of the effort, so understand what you're potentially getting into.

We recently did our product wiki page for other teams to integrate with us. Some tips from there:

1. Who is target audience for it. You mentioned detailing your service. So who is going to read it. Write accordingly. If it's for other teams who consume your service, they want to know what is this service, purpose and how to integrate.

2. Think like a startup. Add a one line overview of what it does.

3. Content must be engaging (animated a bit). Images, videos help.

4. Keep the link in your email signature (for promoting it)

5. Ask for feedback and keep updating it.

6. Make it one shop for all team stuff - team page, contact us, paging information of your team when issues

7. If there are other product's wiki, get some inspirations from there.

All the best!

In terms of tooling: use what you have available today that is accessible to the people who will need to read and write the documentation over the next few weeks and months.

In terms of a categorization framework to arrange the documentation itself, see: https://diataxis.fr/

You can't create a successful wiki alone. Get others bought in and contributing. Nothing worse than spending time on a Wiki that just rots from inattention.

I'd use a lot of screenshots for workflow.

I'd also embed a lot of shadow knowledge, the knowledge that one acknowledges and answers the "why".

If technically possible I'd also setup a monthly notification so that the whole team can sit together and review all wikis created 30~60 days ago. I'd aggressively truncate anything that is wrong, irrelevant or confusing.

Make sure to distinguish between docs that need to stay up-to-date and docs that don’t. Put a date on the docs that don’t.

Start with onboarding page since that's what you will be most familiar with and has actual content and does not change too much. Use screenshots and add version/date of each tool.

Use a tool everyone is already using or familiar too (ideally it doesn't involve logging in or has single-sign-on).

Ask a few people on the team what they’d want to see in the wiki, and suggestions of tools to use. Then use that as an input

Good lord, why is no one mentioning gitbook?