41–50 of 93 posts
I work at a large bank. Mostly people hold all relevant knowledge in their own head, and when they receive a request for information they only respond if their manager knows yours. Then, they will mostly refuse to create any type of actual document and instead request that you set up a meeting with them through Outlook. They are of course completely booked on their Outlook calendar for at least the next few weeks, an…
My name is Omer and I am currently building a knowledge documentation solution called Scribe (formerly Mindflow.ai).
Scribe runs in the background of your development environment and creates documentation based on your workflow. Additionally, we allow for users to easily create their own documentation in an intuitive, easily searchable fashion.
During Y Combinators Startup School we launched our Alpha product, and we are currently building the beta version of our product. If this sounds like it can help, you're more than welcome to sign up!
Solution: Hire a librarian. I'm not kidding in any way. They are massively underemployed and are very good at exactly this task. Back at PBwiki we hired a librarian who not only organized all the things but ended up running and building our support organization. Do not tell them what tool to use, let them own your knowledge base and make their requests for information understood to be P1 priority.
We use mediawiki and and recently IT invested in confluence. I hate it, because it's slow. but I do see it has some benefits, for example, it automatically generates a content table. so content discovery is easier. it is also designed to be a document system for a software company. you can use it to create meeting notes and tag people. but overall, I liked mediawiki, the problem with it is, it's hard to make sure thi…
The information split is very much as you describe between canonical and ephemeral. For the first case, the defacto tool for medium size companies (25-1000) is Confluence (large companies lean towards a custom intranet). Confluence is accessible to the entire company, not just engineers with git and markdown knowhow, it is also well established, very reasonably priced and can be deployed on cloud or on premise. There are drawbacks such poor search and complex organization that makes it hard to find anything, but there is not a clearly better solution at the moment, though there are a few startups like mine trying to change that.
For the second case, companies have tried to deploy an internal StackOverflow / Quora, some homegrown or using open source tool but unless tied to a specific workflow (like all hands Q/A), they are eventually abandoned. The issue is a lot of duplication of content that also changes very often. So long term storage is not as valuable as just removing the initial friction and what seems to work best is an ephemeral solution like a dedicated Slack/Hipchat/Teams/Mattermost/Gitter/Zulip channel.
Andy from Tettra here with some shameless self promotion: My startup is actually working on this exact problem: https://tettra.co Our philosophy is that knowledge should be fast to capture, accessible from your communication tools (Slack, etc) and open by default for everyone on your team to suggest edits because most knowledge goes stale in other systems. Would love feedback from the HN community. We're documentatio…
About the only downside is that sometimes documentation gets outdated and you have to hunt down the current version of a process, but that beats the alternative, where nothing is documented.
Earlier quoted context omitted.
Maybe the problem can be reframed? > the problem is more for processes. Things like "How do I create a build from my commit?" With well set up CI and automated builds, would you need this documentation at all? Could other processes which you currently document also be automated? In my (limited) experience there's no great way to handle documentation, apart from reducing the need for it as much as possible. The team I…
> With well set up CI and automated builds, would you need this documentation at all? We have that. But how would you know that we have that without documentation telling you? How would you know where to find the resulting builds or to check the status?
> We could have the documentation in a separate repository, but if we are going to be making this leap, we want to be sure we are using the right tools for the jobs.
If you haven't considered this yet, it would be very easy to set up a Mkdocs[1] site for testing, using all of your existing documentation. Should be as simple as making a new site and dragging your current docs folder contents into the docs dir. It has good search built in with Lunr[2]. Try the Material theme[3] if looks are important.
[1] http://www.mkdocs.org [2] https://lunrjs.com [3] https://squidfunk.github.io/mkdocs-material/
I have had great success with Mediawiki and Slate. With Mediawiki, you can use Categories, ex: [[Category:NameHere]], and templates (don't forget to update the CSS) for great organization and consistency. The usage of templates will allow you to be DRY, so if you update the template, where it is embedded will update too. And Slate was just a pleasure to work with.
It is great for one thing, everyone can edit it with just their browser. Today, however, you have more options that can do that with a Git+CI backed auto deploy on change.