Live data from Hacker News

Ask HN: What's the best way to organize a company's engineering wiki?

news.ycombinator.com

11–13 of 13 posts

Re: Ask HN: What's the best way to organize a company's engineering wiki?

#11
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.

Re: Ask HN: What's the best way to organize a company's engineering wiki?

#13
post #4

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 colle…

Also many Git web front-ends support formatting some dialect of Markdown documents.

Right. If you're a markdown fan, this is completely doable. If you like PDFs, AsciiDoc plus WeasyPrint or PrinceXML can get you there.
Post reply on HN