Ask HN: What's the best way to organize a company's engineering wiki?
I'm setting up a new Wiki at our company and was wondering what are the best systems, categories, or approach to organizing a wiki so it doesn't become a behemoth.
12 comments
My recommendation is to get rid of it. I put my docs in the repo with the code so we know who wrote it, when they wrote it, what version of the code was current when they wrote it and can easily back out changes if someone wrote something wrong.
I document everything in text, but have a tool that scans text and produces basic HTML with paragraphs and links to images.
That being said... maybe a tool that scans a collection of repos and indexes search terms would be really cool. Right now I can only search my current repo.
IMHO, I believe the problem with wikis is its easy to create a wiki page, but it's hard to figure out if you should remove a page. With the "docs in repo" approach, we're okay with removing docs since it's relatively easy to bring them back.
I document everything in text, but have a tool that scans text and produces basic HTML with paragraphs and links to images.
That being said... maybe a tool that scans a collection of repos and indexes search terms would be really cool. Right now I can only search my current repo.
IMHO, I believe the problem with wikis is its easy to create a wiki page, but it's hard to figure out if you should remove a page. With the "docs in repo" approach, we're okay with removing docs since it's relatively easy to bring them back.
A couple more benefits to this approach come when you do code reviews and other developers on the team have an opportunity to provide feedback and are more aware of what docs are available.
There are two main problems with wikis : Maintaining and Finding.
I'll start with the second, because it is 2023, and wikis are finally embracing semantic search [0]. This will not only almost solve this problem, it will also alleviate the need for heavy handed content organization in general (categories..)
The first problem is best solved IMO with getting someone responsible for gardening it, as someone put it in this thread. There are products designed for smoothing the process [1], but a human gardener is still you best bet.
[0] https://slite.com/ask is the first enterprise wiki I've seen integrating this.
[1] A recent exple for code documentation is https://swimm.io/
I'll start with the second, because it is 2023, and wikis are finally embracing semantic search [0]. This will not only almost solve this problem, it will also alleviate the need for heavy handed content organization in general (categories..)
The first problem is best solved IMO with getting someone responsible for gardening it, as someone put it in this thread. There are products designed for smoothing the process [1], but a human gardener is still you best bet.
[0] https://slite.com/ask is the first enterprise wiki I've seen integrating this.
[1] A recent exple for code documentation is https://swimm.io/
Wikis end up being a poorly generalized dump of poorly structured info combined with an information discovery problem.
What do you want to put in it? How to do things? Runbooks for common problems? Explanations of how systems function? API Documentation?
Why not generalize it and make it discoverable.
If it's a "how to" it should probably be in the repo in a top level directory.
If it's a runbook, why not keep a google doc link next to your alerts?
If it's api documentation, I think there's plenty of software for that.
If nothing else, why not create a data structure in your repo's top level directory that lists persons, teams, or services and documentation associated with them
Why invoke an entire service with a database that needs maintenance, security, and some notion of accounts?
My question for you is: what do you hope to achieve by setting up a wiki? What can a wiki do that nested google docs can't?
What do you want to put in it? How to do things? Runbooks for common problems? Explanations of how systems function? API Documentation?
Why not generalize it and make it discoverable.
If it's a "how to" it should probably be in the repo in a top level directory.
If it's a runbook, why not keep a google doc link next to your alerts?
If it's api documentation, I think there's plenty of software for that.
If nothing else, why not create a data structure in your repo's top level directory that lists persons, teams, or services and documentation associated with them
api_team:
public_docs:
"Public API Doc": "https://..."
"Internal API Doc": "https://..."
important_design_docs:
- "https://..."
- "https://..."
run_book: "https://..."
onboarding_doc: "https://..."
architecture_spec: "https://..."
members:
- jane
- jim
ops_scripts:
- push.py
- rollback.py
- drain_region.py
dashboard: "https://..."
Why invoke an entire service with a database that needs maintenance, security, and some notion of accounts?
My question for you is: what do you hope to achieve by setting up a wiki? What can a wiki do that nested google docs can't?
Unless you have a person responsible for organizing the wiki, you'll end up with a lot of documents / pages the bigger the team is.
Three of the aspects to look at that could make your life easier are:
- a tool that allows great UX for easy linking between documents / pages / folders
- the way the wiki is structured and how enforced this structure is
- rich options for embeds that you can integrate in your wiki
Easy linking / autocomplete of pages is really helpful to interlink your wiki and update old content at the same time. The better the UX, the less likely it is that people leave outdated information or documents that nobody checked for a long time.
Regarding structure - you could pick a system that enforces folders or a tree-like structure but both options have the problem of trying to fit all documents into categories. Something more flexible might help having an organized wiki without thinking about its structure. Saga (https://saga.so) solves this in an interesting way with collections (a mix of folders and tags) and page linking.
Three of the aspects to look at that could make your life easier are:
- a tool that allows great UX for easy linking between documents / pages / folders
- the way the wiki is structured and how enforced this structure is
- rich options for embeds that you can integrate in your wiki
Easy linking / autocomplete of pages is really helpful to interlink your wiki and update old content at the same time. The better the UX, the less likely it is that people leave outdated information or documents that nobody checked for a long time.
Regarding structure - you could pick a system that enforces folders or a tree-like structure but both options have the problem of trying to fit all documents into categories. Something more flexible might help having an organized wiki without thinking about its structure. Saga (https://saga.so) solves this in an interesting way with collections (a mix of folders and tags) and page linking.
We tackle this hard with slite.com, we just introduced slite.com/ask to find answer no matter how badly organised your documents are, and we offer document status to track outdated and up to date docs across your space (and we're still enhancing it, very much first version).
These among many others to help it not become a behemoth as you say.
These among many others to help it not become a behemoth as you say.
I have seen different wikis. It's definitely possible to create a good useful wiki contrary to some of the comments here.
Concerning the best way, have someone responsible for gardening it. Otherwise, it might grow into a terrible mess.
Concerning the best way, have someone responsible for gardening it. Otherwise, it might grow into a terrible mess.
Take a look at the Arch Linux wiki as a source of inspiration.
A full scaled wiki should be a behemoth IMHO. However maybe the most important part is to link it to other stuffs, e.g. code.
really not trying to blogspam but wrote this article on info architecture in a wiki for Slite – hope it helps: https://slite.com/blog/how-to-build-a-company-wiki-that-does...