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.
Ask HN: What's the best way to organize a company's engineering wiki?
1–10 of 13 posts
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#2My 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.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#3A full scaled wiki should be a behemoth IMHO. However maybe the most important part is to link it to other stuffs, e.g. code.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#4My 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 colle…
Also many Git web front-ends support formatting some dialect of Markdown documents.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#5My 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 colle…
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.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#6I 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.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#7Wikis 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
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?
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#8Take a look at the Arch Linux wiki as a source of inspiration.
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#9There 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/
Re: Ask HN: What's the best way to organize a company's engineering wiki?
#10We 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.