Ask HN: How does your team handle knowledge documentation? | Hacker News Reader

Ask HN: How does your team handle knowledge documentation?

111 pointsdalemyers90 comments

We are currently going through a rethink of our documentation (not for customers, just our internal processes, tools, etc.). Currently we have a docs directory in the root of our project repository which holds a bunch of markdown files, but we are beginning to grow out of this. Keeping links accurate and update to date isn't too much of a challenge, it's the barrier to entry. Filing a PR to make a minor documentation change is just too much. 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.

The way we see it, we are going to end up requiring at least 2 different types of documentation. The first is our deep documentation of our tools. This explains exactly what it is, how it works, etc. and is designed for people who want to work on these sorts of tools, not with them. The second is a quick fire Q&A. "I'm having issue X, how do I fix it?" Think StackOverflow.

So, what does your team do for these challenges? How effective is your solution? What do you think would be better?

View on HN

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, and then when you do get to talk to them they use obtuse department-specific acronyms as much as possible so that by the time you've started to understand the surface of their answer they have to leave for an urgent meeting.

Hoooly, that is terrible!

Best part is when they retire and then no-one knows anything about anything. Then the Company is forced to hire them back on as contractors (at $500/hr, minimum 25 hours, of course)

what's crazy is if bank managers cared at all about making their organizations a learning organization this is priority #1. instead they prioritize hiring people over figuring out what they do after they're hired.

Having spent many years in a company with banks as clients, thank you for so clearly confirming what I have always suspected.

I thought I didn't work at a large bank but you're making me doubt that, we must be in the same building.

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.

I'll second that. In one company I worked at we had a tech writer we could throw stuff at and she did the work of structuring and editing. This worked great.

I am afraid that the idea of hiring an expert for a specialized task goes against the trend of "full-stack developers".

Imagine explaining why it is not necessary for the project to have a database expert, a back-end expert, or a web expert... but you definitely need a wiki-pages-organizing expert.

The librarian is not for a single project, but the entire company. The librarian's job is to make sure that as much information as possible is stored in a manner that is searchable and accessible to all employees who need the information when they need it with minimal effort.

Perhaps that's a cue that "full stack developer" is just a cute buzzword for "jack of all trades, master of none".

This is a brilliant idea.

I really never thought of actually having a person responsible for internal corporate knowledge, but it makes a lot of sense!

At Vistaprint, we used MediaWiki, hired a dedicated librarian, and, most importantly, had a culture of documenting everything on the wiki. The last point is most important. Everyone in the organization _must_ adopt the mindset of checking the wiki first. If the information is not on the wiki, figure it out, and put on the wiki. I vaguely remember wiki articles even being a (minor) metric for annual reviews. At one point, Vistaprint tried SharePoint but we quickly went back to MediaWiki.

At edX we have information spread between Confluence and Google Drive. Search is not ideal for either. Information sharing is not great.

Disclosure: I am the founder of a company that aims to solve this first documentation case you pose. But the process of validating this problem and get early feedback on our solution, I interviewed to dozens of companies to learn about their tools and processes, and hopefully some of that can be helpful here.

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.

what is the company called you founded?

The company is called Slab (somewhat of a double reference to a thing you can write on and slab serif fonts). It is current in private beta but if you would like to take an early look please find my email in my profile and I would be happy to share with HN.

How is your solution different?

We is much simpler and easy to use and plays well with the non-Atlasssian ecosystem (as well as with JIRA). In both these regards we like to think of ourselves to Confluence as Slack is to Hipchat.

The PR isn't your problem. There will be some other other problem you'll find with any new documentation system. The root cause is keeping documentation up to date is universally a pain. Unless you have it as (part of) someones job, it always will be subject to decay.

If someone has "solved" creating a good way to capture tribal knowledge, I'm all ears. But it's not the tools being used that are the issue or the solution.

Our company has a culture of making it a part of the dev owner (or product owner's) job. So as part of shipping a feature / epic / task you are expected to create and update documentation. The added benefit is when someone has a question you point them to the document and make sure they read it before scheduling a meeting.

In my opinion you are on the right track with the project holding a Documentation folder and the markdown files. Keep it all together or you will have yet another place to maintain.

I would suggest adding the use of Doxygen to your projects. It supports Markdown files as well as Markdown syntax in your code comments. You might find that a lot of what you are documenting in the separate .md files could be a notes or remarks section of your method class comments. This will remove the separation of technical documentation vs. help/FAQ comments by doing all of the documentation in the code. You can then add Doxygen to your build, so that building the project refreshes the documentation. Doxygen can be configured to produce a online html version that can be deployed to an internal web server for quick reference. It can also build .pdf, rich text documents, and unix man pages.

Then if you use Continuous integration/deployment, when you deploy to test, UAT, then eventually production you deploy the official documentation that was generated.

The challenge with all documentation, is, Actually doing it. So it should be part of your SDLC documentation and process. the project/task/request is not done until documentation updated. Make it a checklist item that needs to be reviewed in code reviews. Doing the technical and help/FAQ all in code comments makes that easy.

cheers!

We already have this, the problem is more for processes. Things like "How do I create a build from my commit?". We have dedicated documentation which explains how the build system works in it's entirety as markdown files, but it's painful for a new team member to have to go through that and find out what they need.

A simple Q&A document is failing us as well due to the fact that all commits to our main branches need to go through PR which puts in a high barrier to entry for what might be a minor change. It just discourages collaboration in so many ways.

Why not relax the PR process for the docs directory? If your process is in the way of progress, change the process!

We can't unfortunately. With Github it's all or nothing. We need to enforce code reviews for all merges for certain branches anyway for legal reasons.

So why not have a docs branch open for direct commits, and then merge it into 'certain branches' at meaningful points - release, or whatever?

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'm on (as a PM, I'm not a programmer) used to use Confluence for almost all technical documentation, apart from the odd Readme file. We use it for product, product range and other team documentation too, which makes choosing sensible top level hierarchy difficult! I don't recommend trying this.

But we finally have decent automated builds in place, and it's made a world of difference. We will soon have decent CI set up too (with Gitlab), at which point lots of project specific technical documentation will move to Gitlab wikis, living alongside the repo it relates to.

> 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?

Fair enough. We currently document such systems details in Confluence, which I can't recommend for all the reasons given by others here.

> 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/

Our company uses Confluence and I highly recommend it. I think it does a very good for keeping your documentation "fresh" because:

* It's easy to search and find things

* It's easy to be notified of updates

* It's easy to comment & edit (for both non technical and technical members)

* It's easy to create quick documentation through the Q&A product and use the wiki for longer documentation

The main cons I've found with Confluence is:

* The general UX is weak (this is the case across all Atlassian products in my opinion)

* The markup language is not markdown

* The edit & save UX is a bit too heavy, your changes don't get saved automatically but rather it requires a separate button change. So documentation changes are a bit slower than something like Google Docs

Despite these cons, Confluence has been great for us. However, in order for any tool to work there also has to be a cultural shift. Our company is very good about:

1) Keeping knowledge not silo'd in brains of devs or other tools. So whenever I ask any senior dev a basic question like "How do I get unit test coverage?" they will immediately link you to a confluence Q&A answer or if one isn't created they will give you the solution and immediately ask you to create a confluence question.

2) Not spreading knowledge across other tools - any process, decision, design, etc. is required to be in Confluence. Any thing in Slack, Email, or Google Drive is immediately asked to be moved into Confluence.

I work in a department that develops and maintains an internal SDK used by internal BIUs to develop medical applications. Size of codebase is well over 1 Million LoC.

We heavily user source code documentation for all public API which is enforced by our internal build tools (build breaks when undocumented code is found) and the review process (to check if documentation is proper). We have a searchable themed MkDocs page with a large number of “how to properly document X”. Reviewers actively place links to these pages in the reviews where source code documentation is not proper (style issues, lacking, no examples, etc).

Goal is here to have a proper MSDN like source code documentation and site generated by Doxygen. Each release gets its own documentation, which is easy as it is just a source control revision. A second goal is to have most of the documentation as close to the code as possible so it actually stays well updated.

Next to this we have a developer portal which is based on manually written markdown files. We are currently in the process of replacing our existing media wiki pages into markdown as well. Markdown is quite powerful as most people can easily read it, even with just notepad. In addition it converts to anything so it feels a bit more future proof. Right now we put it in a slightly extended mkdocs served site. We extended a bit for versioning and a landing page that links to separate mkdocs sites as the navigation becomes too cluttered if we put all of our layers and components in one site. Better to branch Early is what we found. So separate sites for database, infrastructure, system (multi-subsystem deployments), application development (wpf, HTML5,..),and for each subsystem (printing, auditing, reporting, data server, ...).

The problem is already we notice the manual markdown is not properly maintained. I think this is a problem you never solve unless you hire people to do it full time. I.e technical writers.

My personal opinion is that a stack overflow enterprise (on-premis SO) is more powerful. Nowadays people want to know “how” instead of “what”. A Q&A site with tons of questions and answers is much better than a one-way written developer portal. Also, other people outside of our department could also answer questions for us. As a benefit you learn where people struggle with your API or use it for things it was not developed for. Feedback is great here.

Do you mind to share what kind of X in “how to properly document X” pages you have? I like that idea and would like to do similar!

I wouldn’t mind but our bureaucracy organ does :(. Whilst technically it is only moving the markdown files and CIconfig from our private gitlab to a public one, the bureaucracy involved with it prevents me from doing it today. I would have to pull a part of our source code which is under strict regulation, and I try to only start that process when I absolutely must do so (subsidiary projects mostly).

The contents are free to describe though. Essentially you would find a large number of pages on all language concepts for our main languages. So “how to document a method”, “how to document a property”, classes, namespaces, you get the idea.

Next, we have a very clear setup in our documentation pages. All pages and sections on pages have permalinks. The idea is that you can redirect people to the exact information they have to read. Every section always starts with three examples. The examples are different enough to be applicable to say 80% of the cases. This means most of time a developer does not need to read more than the examples, c/p one and adjust to his specific case.

After the example cases the different aspects are discussed that should be in. This includes rules like “use the 3rd person when writing descriptions”, “use present tense”, “start with active verb” but also “include minimally one example in the format above” and “never use the name of X in the description”. (I.e SetSomeCrypticThingOnlyWeUnderstand() // sets the cryptic thing << not helpful). Basically a checklist. Typically we have DO, Don’t, and AVOID listings.

After that (bullet/checklist) usually a paragraph describing the rationale for documenting like this as well as other information not captured in the examples or bullets.

Sometimes after this there is a section of “also consider” where we capture issues of the past. E.g “when documenting X that uses units, specify the units.”. I.e if you have a property Angle document it is degrees or radians. That same page would probably have a paragraph on should you name “Angle” or AngleInRadians or some info on avoiding ambiguous naming of properties.

I’d say the biggest game changers are the permalinks, good golden samples at the start of each section and in some cases bullet lists. The description paragraph is optional.

All our pages are markdown pages served on Gitlab Pages (on premise deployment) as static site built with MkDocs and Material theme (slightly customized) [1]. All pages include an “edit on gitlab” button so users can edit the pages in their browser without downloading any tooling. A CI setup will auto redeploy on commit/push. If clone the repo and you download MkDocs locally you can of course write with live reload etc on a local server (MkDocs serve).

O, and have a great search functionality and decent responsive website that is easy to read (good font, colors, syntax highlighting etc).

[1] https://squidfunk.github.io/mkdocs-material/

What a great informative reply, really.

  Thank you.

I will definitely start to create a similar meta-documentation for our department as well.

Really how can we expect anyone to properly document anything when not specifying how? It is so obvious now.

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 things are up-to-date. and it's difficult to do content discovery.

We too use Confluence and it's abundantly unbelievably awful.

* Super bloated and laggy

* Hard to get your data out/migrate to some rival system. Did your technical writers spend a bunch of time typing strings into a table using the Confluence table building GUI, and now you want that data as a .csv? Too bad, hope you want to spend half an hour in copy-and-paste + reformatting hell.

* Impressively broken search (e.g. if you create a page named "foo" and then search for "foo," you'll often get pages of unrelated results that do not include your page called foo)

* Can't natively show typeset math. Doing so requires plugins that are somehow both expensive, broken, and only compatible with narrow ranges of Confluence versions.

* Gross nonstandard markdown dialect

These are just the shortcomings that I can think of right now. However I think even Confluence is probably better than submitting PR's for docs changes as the OP mentions, since at least it's a wiki.

These are basically the same issues we have. We've ruled it out entirely as a suggestion. Markdown documents and searching on disk is better than Confluence.

Yep, also use confluence wiki for a customer and it is horrible. For another company I use mediawiki. Nothing beats that.

Easy to edit, easy to maintain, good search capabilities, plenty of ways to extend.

Edit: for updates of mediawiki use installatron, for structuring documentation you can use categories.

There are some big confluence UI annoyances though:

- wide screen support (paragraphs to across the whole screen)

- Every page is a folder and the add-button is visually above the current page in the hierarchy, but creates a child page. Easy for techies once they figured it out, hard for new people and the rest of the company.

- no tree-view by default

- comments can't be seen in edit-mode

- no markdown

Biggest pro though:

- collaborative editing in a wiki (and still a dedicated edit-mode so work in progress remains hidden from those trying to just read the resource)

Pretty sure on a blank page Confluence has no table of contents. I am always adding those to pages. Maybe you are using a template. My recollection of using MediaWiki is that it was also better in that regard.

Confluence is not worth using with Jira. It's true ability to shine is in how well the two can integrate. You can effectively have design doc driven project management with a few clicks and save a ton of duplication of effort between your documentation and project tracking efforts.

How? Badly.

Right now it's a GitHub wiki in our "infrastructure" repo (which is basically all the bits and pieces that don't fit anywhere and don't have a proper repo of their own). We migrated to this from: "several github wikis, each in the repo of the project" - but often you have overlap and it was bad to find stuff.

Pros:

- easy backup (git clone)

- markdown

- easy to get started, "good enough"

Meh:

- searchable only with a browser extension

Contra:

- some coworkers don't like the github wiki

My dream (never happened in any company as of now) would be a single document (think: the manual), hopefully editable in a proper way (I am not sure if checking in changes in a doc/ folder in a code repo is the way to go for <10-20 people) that's hopefully displayable in a browser (and not a PDF, and ESPECIALLY not a Google doc) with cross-references.

Good to know that Github wikis aren't searchable. We have a Github Enterprise installation and were considering using the wiki for our longer, detailed documentation, but lack of search is a no go I think.

You can search on Github wikis. You enter your query in the search bar to the right of the Github logo. I guess wink hasn't tried to in the past year (https://github.com/blog/2219-search-wiki-pages).

Wow, now that's undiscoverable. Thank you, missed that one completeley

Blog post is from August 2016 "You can now search for wiki pages from either the main search page, or within a repository."

Guess I made up my mind about that 1-3 years earlier and have used the extension ever since :) Ah well, one click less at least.

gitit is a lightweight wiki that:

reads markdown

has an online editor available

stores in git

and is searchable.

> How? Badly.

I was about to make this same joke. Glad to hear that everyone is just as screwed on this.

Don't use confluence :( In every team I've been, confluence feels like an huge hole, we can never find what we are looking for...

That's probably because you've used Confluence. If you used something else, then that'd have been the huge hole.

Confluence is a very good wiki. There's no wiki that creates good structures for you automagically.

We actually used Confluence but moved away from it. The interface was difficult to use, it was slow, the search wasn't great, etc.

yeah, same pains that I've felt. I get the feeling that Atlassian products always lack some UI love

Away from Confluence and to the documentation directories?

Confluence is still the best Wiki out there for general documentation itself, in my opinion. It takes work though to create the initial structure with a realistic view of how projects will evolve, and to make sure that everything is reachable through an organized hierarchy (or lattice, or DAG) reachable from the Space root. What sucks is random "floating" pages not tied to anything else -- these get lost.

There are various orthogonal concerns to deal with when documenting software development with Confluence:

+ knowing the underlying platforms / technologies your project uses

+ architecture / design of system (which will evolve over releases) -- Gliffy plugin works well for illustrations

+ documenting releases

+ engineering-level precursors to user documentation

+ meetings -- high-level overview of discussions, decisions, resulting actions

+ Confluence wiki integration with bug-tracker, source code repositories

Without an up-front design one will run into problems. Even worse if managing several projects.

Definitely don't use SharePoint either! It's the ultimate data black hole.

This! As we use JIRA for ticketing we thought Confluence would be the best way. But like you said the problem is not that the information is not there. The problem is that the information is not findable and the search is in my opinion really poor.

To solve that problem we started with a "doc" directory in each repository holding multiple markdown files for each topic. That way all of our developers are able to find the information they need (even without an internet connection).

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.

FWIW we are moving out of MediaWiki after 10 years. The search function is horrible and the readability on any devices is not great either (understatement). The latter is with our theme, not sure if you can theme properly. Long sentences, no proper image positioning and scaling, mobile support is lacking, etc. Also versioning is a problem when you need both versions of the page to be readable (e.g. 1.0 and 1.1).

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.

Did you ever try Elasticsearch on your MediaWiki instance?

If you want to maintain documentation for different versions of the same software then consider AsciiBinder. http://asciibinder.org/

For example, Openshift Origin documentation uses it: https://docs.openshift.org/3.6/architecture/index.html

There is Mkdocs (http://www.mkdocs.org/) which is a static site generator targeted towards project documentation. This is more straight-forward and easier to maintain. Both are open source software. You can give them a try and see if you can tailor them to your needs.

From what I have seen creating up to date documents is considered superfluous. There are tons of excuses for why people are not updating the documents. Raising a PR for small changes is one of those excuses.

Any tool you find will have it's own version control restrictions. People will use that as a crutch to say - Well, the tool x has steps a, b, c which is too much of hassle for a minor change.

This cannot be solved by using better tools or solutions.

To give examples from my experience:

One of the places where I saw the best documentation was at a bank. Every project came with specific amount of time dedicated to updating documentation. This ensured people don't complain about not having time or the process being tedious etc.

Though as there was no time allocated for peer review of document control - It did not stop people from being lazy or creating dependencies by knowingly adding generic information in the document.

In worst of places, a software product company - documentation was looked down upon. Everyone was more than happy to "set up time to discuss" than put actual effort in good documentation. As I joined after the aforementioned bank, I had a habit of abhorring meetings and creating up to date document which was shared with the team.

The end result was that people still wanted to have meetings. On being told, I shared document with relevant info with them, they used act surprised and ask to share the document again.

Alfresco is an open source Enterprise content management software which has frontend UI called Alfresco Share. The installation is simple using their all inclusive executable which bundles the server, database, and Solr for searching any and all data. It also has this concept of business workflows which you say is a pain point for you. Each document can have workflows assigned to it at which point it has a life of it's own, passing from user to user, emailing itself, tagging itself, etc. There is a learning curve on the dev side, especially if you aren't Java savvy, but once you get the hang of it it's very powerful. I've personally written an API in Lua for syncing documents. I assign bot accounts from the Share UI which are given permission to crawl and sync directories to bot accounts on the server (origin server or external server), and each bot has a job to do on each document it gets, for which it writes and dispatches a service with systemd, then uploads the processed documents back to alfresco. And this is probably 1% of what Alfresco is actually capable of (and my implemention reeks of hackiness, because I hate Java). A team of devs is bound to get more use out of it.

TL;DR

* we use Slate for API docs, Google Sites for company documentation (and some Google Docs) * am thinking about using a forum for Q&A e.g. Discourse [2]

Longer:

We've also been going through some thinking on this. At the moment we have an API docs page using Slate, and a Google Sites site which contains a whole raft of documentation. We still have some stuff in Google Docs as well.

Our problem is that not all the team is part of Engineering, so keeping stuff in the repo isn't really ideal (hard to edit). Google Sites is fine but its main selling point is easy access to Google Auth. I have a thread on HN about this [1].

One of the things I have been thinking of is setting up a forum like Discourse [2] for Q&A. Sales often has product-based questions, and vice-versa. In my view, this beats other ways of asking questions (e.g. Slack) because there's no time pressure to answer, and unlike "office-hours" style meetings, it's automatically documented. The only problem is that it is yet another tool.

[1]: https://news.ycombinator.com/item?id=12540678 [2]: https://discourse.org

>The only problem is that it is yet another tool.

That's one of the main horrors we are trying to avoid. We'd like to have a single location to track both kinds of documentation ideally, but realise we are probably going to have to make compromises. Tools which keep things in a standard format will ease migration in the future, so something like Slate would be nice and looks a little better than our current way of "Go view the file in Github".

Have done this role a couple of times. You need to make one person responsible for documentation and traceability, because collaborative editing in a wiki like tool without some editorial oversight and organisation leads to problems later on. The tool really doesn't matter, Confluence works well with Jira, pwiki is nice to use, even sharepoint works in a pinch. Heck, I've even used Enterprise Architect and Mindjet MindManager!

We have a lot of teams using HelpSite.io [1] for this sort of thing. Originally designed for customer-facing FAQs, we also support the same format for internal knowledge bases. We didn't originally intend to support such use cases, but it turned out a lot of people really like our format for internal company docs as well.

[1] https://helpsite.io

we have a 2 repository in a gitlab group named "knowledge base", one for public information, one for private information. AND we use a opensource stakcoverflow clone (askbot)

for the git repositories

so that developers works with markdown files, it can be git cloned, it can be grepped, but it can also be rendered in the gitlab website, and most importantly compared to other wiki's or even gitlab's wiki, you can make merge request, so that,

  * if you fear to put an incomplete things, at most it will be in a MR and get reviewed (or never) but at least it's somewhere else than in your head
  * all knowledge merged has been known to be there by someone else, so that it's ot just a wiki full of hidden gems that everyone has buried and nobody else know it exists

This way you have encyclopedic knowledge of "how to put a new project in our CI/CD pipeline" or "list of horrors in project X that you want to delete, but hey that's not so simple and here's why"

the stackoverflow clone on the other hand is here to answer the question everybody ask, from the new employee to the famous "oh why god already do we have to do this command everytime e deploy, I remember John explained it to me one day?" the stackoverflow links extensively to the repository for the "if you want to know more"

we also put as much as possible the "as of march 2017" marker, to always remember people that information rot

things we also do:

every todo in the code has with it a link to the corresponding issue in the tracker, so that when you have 10 minutes to kill, you can check the tracker for "TODO" issues, and grep "TODO #42" in the code

We just started using Guru (getguru.com) for our 13-person remote team (trydesignlab.com), and it's been quite effective. Some key features that we love:

- Simple UI with well-known metaphors like cards and collections — each task or process you have as a company can live in a separate card

- Tagging combined with lightning-fast search

- A bookmarklet that allows you to search your Guru knowledge base from any other site you're on (really handy for our support agents who want to look up a manual process without leaving their support workflow in Zendesk)

- A "verification" workflow that ensures your knowledge base is up-to-date (previously a huge issue in any sort of wiki / document-based solution — you never know if what you're reading is the latest piece of info, or whether it's been updated since). Cards can be assigned to an owner who can be reminded to verify the information on a periodic basis (e.g. every 2 weeks, 4 weeks, etc.), and anyone viewing a card knows whether it's been recently verified

- The ability to ask questions to individuals / groups within Guru, with answers turned into new cards. Instead of tapping someone's shoulder (or sending them a Slack message), we now ask for info within Guru, organically growing our team's shared knowledge base over time

Overall this has been a tremendous find for us. We had a number of core processes (support, operations, payments, dev, marketing, sales) that lived in various Google Docs (including one monolithic 'Process Guide' doc), but that system was growing extremely cumbersome to use. We strongly considered Confluence, but stayed away after a short trial revealed how bloated the product was — we knew ramping the team up would be a nightmare.

So far Guru's been a winner — would recommend giving it a spin.

We use Jingo (https://github.com/claudioc/jingo), which is inspired by GitHub's wiki (i.e. is a git repo itself) but with has search function. It's not the best experience on the planet, but it works and is easy to self-host.

We have a 'this person better not be hit by a bus or quit on us' policy, or nearly so.

We have people get assigned tasks from other projects from time to time, and they start picking up bits and pieces of the projects from that. And we have an internal wiki that documents some things that people aren't very good about keeping up to date or making it comprehensive.

Also some of our software has gone through rewrites that has cleaned up the architecture and made them easier to understand and work with, without documentation.

But there's still way too much locked in people's heads. We've lost quite a bit of it, too, as people have left over time. I know we're trying to convince a client to shift over to newer versions of our software, because we no longer have anyone that knows anything about the tech the legacy legacy software was written in (it's legacy software that predates our existing legacy software).

We are using Jive for all of our internal documentation which works really well for us. For deep documentation, both new document requests and document updates are submitted using a built-in "Ideas" feature. "Ideas" can include plain text, links, images, or videos, and can be submitted by anyone in the company. With this information, we can create a new document, save it in Jive, and then respond to the "Idea" with a "The document is done and here's the link to it" comment. For quick fire Q&A, we've created a page in Jive that uses built-in "Questions" and "Answers" features, again, accessible to anyone in the company. Jive's search feature is pretty robust (keyword-indexes anything you add to it without having to create tags, though you can add tags if you want).

For Semantic Synchrony[1], we keep our notes in Semantic Synchrony, a knowledge graph server (written in Java, using Gremlin and Neo4j) and client (Emacs). It allows for selective sharing, and you can connect your private notes to your shared notes however you like -- for instance, I've got a lot of "half-formed hypothesis" notes that I don't think are worth anybody else's time, so I keep those private. It eliminates the dead link problem, and the linearity constraints that trees (let alone flat folders or text files) impose.

It's open-source, with a lot of features, and well documented.

[1] https://github.com/synchrony/smsn/wiki

For just files (Word, Excel, CAD, pdf, PowerPoint, etc.) PDM/PLM software is amazing (some top products include Teamcenter, Windchill, & Enovia). They are tailor made to store the versions (including mark-ups) and provide workfows for approval, since they are born out of the need to store CAD parts/assemblies that have strictly defined parent/child relationships, they have no problems doing the same for more simple files.

For the "why" or "knowledge capture", I don't think you can do better than a Wiki and the dominant enterprise Wiki is most certainly MediaWiki. With extensions for improved searching, visual editor, etc., corporate wikis are more powerful and easier than ever to use.

Hey, I can recommend https://zenkit.com . It´s an all-in-one project management platform with additional handy features for knowledge management. Basically, you can create a collection of all your data and add labels to keep everything organized. The collaborative features allow you to invite your team. Other functions like the global search feature lets you search through the whole app and find information you need (great for FAQ´s - type in a problem and get the documented problem + solution). Also, you can link the tool to over 750 other tools with Zapier and integrate your Google Calendar. Disclaimer: I work at Zenkit.

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 documentation geeks here and love talking about this stuff.

If you're interested in using the product, we can offer a special HN discount of 20% off the first three months. Just shoot us a message in the chat. I'm on there right now.

Your site badly needs a sample of what tettra looks like in action. I have absolutely no clue if you are worth trying out at this point.

Thanks for the feedback, and I 100% agree with you. We're working on it.

Want to shoot me an email and I'll send you an update when it's live? andy [at] tettra [dot] co

We use a wiki where everybody can update, without any review process.

My personal preference is to try to write the docs from a "customer" perspective, i.e. not for me that I know the system, but from the perspective of another employee that sees an issue and finds my page.

This means:

- keywords in the title, so the search autocomplete hopefully will find the page in the first results

- short and sweet, meaning that if a process is more than 3-5 steps, the person won't read/understand it. It's better to improve the process than to provide better docs

- when I read something that doesn't work, I do my best to fix it, even if I'm in a rush

I work for a Fortune 50 and we use Confluence. For us it works well, because we have more teams here than I can count, and people move between teams (and teams move between business units) all the time. So the standard rule is that if you build something, you are expected to document it in the Wiki.

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.

You can try forcing people to write documentation for every new feature they make. Do not let merging without a documentation. Added major feature - ask them to write a post about it on some documentation platform (for example, Confluence). Old methods could be documented whenever you interact with it. Step by step, slowly but surely you're gonna cover your project with good doc

Small IT team, in public health, using MediaWiki on Windows.

Search was underwhelming for our 400 or so pages, so we tuned an old MW extension called RigorousSearch, see https://github.com/thomasswilliams/RigorousSearch-MediaWiki-...

We used MediaWiki for documentations, however we were very unhappy with it. We have almost all an computer science background, but did not like the MediaWiki syntax and the interface.

We created Teamemo (https://teamemo.com) because knowledge management should be easy, fast and fun.

Did you try MediaWiki's Visual Editor?

We use a mixture of Asana and Google Drive.

Asana is an amazing tool to store information as well as create a unified workspace where all members can share work, collaborate on projects/tasks, or have a knowledge repository. Would definitely recommend!

Hey everyone :)

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!

http://mindflowai.com

Tangent: I remember the first time I used Quora, thinking that it had a great model of content discovery and collaborative answering — that it would be fantastic if they let companies deploy internal versions of it. Now that Quora has been around for 7 years and has clearly decided not to do this but instead to make money by , does anyone have any guesses as to why they decided not to?

An alternative for this case for you might be the enterprise version of StackOverflow? We have that internally at the company, but it's not particularly friendly for the use cases our small team has.

Nuclino has been a winner for us.

OneNote - it might not be excellent, but it's got a super low barrier to entry.

Documentation, the thing most agree is a good idea, but nobody wants to do. It's a nuanced subject.

TOOLS

Until recently, we used a combination of Documentum and EPM (Enterprise Project Manager). The intended workflow was to have all documents start in EPM as part of the initial project implementing/building whatever product. When the project closed then the developer was to copy the documents across to Documentum. It was simple in concept. Due to technical shortcomings, it was not. I stopped even trying around 3-4 years ago.

Documentum was a technical horror show. Ten years ago, and for a long time afterward, it supported only one browser, I believe IE. Architecturally, it seemed to use a Java applet for login and, upon successful login, it downloaded an app. Of course, the app wanted a specific version of the JRE locally. But, the real nightmare was authorization. One day you had permissions to update “cabinets” for your documentation. The next day you didn’t. No explanation.

EPM had authorization issues similar to Documentum’s with the added bonus of a project’s link not working all the time. One day you could use the link, which the PM sent out at the start of a project, to access the project workspace. The next day you couldn’t find the project workspace.

Currently, we're moving into a SharePoint site that is more promising. It provides Wiki capability for quick reference items, as well as, a repo for more involved documentation. Apparently, it provides versioning, but we haven't explored it yet.

TYPES

Part of the problem with the subject of documentation is that different groups want different types of documentation. Somehow, the developer is supposed to understand the needs of each group and produce a document tailored to those needs.

Operational people want information on jobs and job dependencies. Support people want lists of things to check and try in case errors occur. (Developers are inherently bad at documentation for customer support. The problem is that we know how the system is supposed to work, so we’re blind to its shortcomings until a user finds them. Rather than my writing a support document upfront, I prefer meeting support people periodically so they can ask questions and develop their own document.)

Management wants everything, all at once. They want it in the amount they want it, summarized, but detailed enough that they can feel like they’re a help during outages and architectural meetings alike.

Users want to know every step for every task they need to accomplish, as well as, what to do in any anomaly, like not paying attention to dialog boxes and hitting “Save” to commit information that they didn’t want to commit.

ISSUES

The major issues, for me, are keeping documentation current and writing for such varied audiences, nevermind having the storage system working against me.

Anybody tried Dropbox Paper?

I work with a large (multi-billion, multi-national) tech company that has a big problem with knowledge management.

My job involves consulting to lots of customers in different industry sectors, and the one small, sad comfort is that almost no one does documentation management well.

Currently if I want some specific tidbit of information I can consult: our knowledge base (bespoke), our collection of product PDF's, salesforce documentation repository, quickbase documentation repository, an aging wiki (twiki), private stash of documents created by colleagues, mailing lists (a subset of which are indexed and accessible from the wiki, otherwise you can only go back as long as you've been with the organisation, and hope you've been subscribed to all the right lists), sharepoint (meant to replace the wiki, but two years later, and no), our learning management system, yammer (seriously), bugzilla, our customer support forums ... or I think about who might know the answer and email them.

My advice as a result of this:

Even if you don't hire a librarian, at the very least appoint a curator -- ultimately you need someone who owns your documentation, and the design and management processes around it, and can encourage/force people to update it, continually reduce redundancy, improve quality, etc etc.

Be wary of your current thinking " We'd like to have a single location to track both kinds of documentation ..." - specifically that there are only two kinds of documentation. Or indeed only n kinds of documentation.

It's easy to fall into the 'let's build a new system to encompass the others' trap (insert obxkcd) and hard to fight it. If you do go down that path, ensure the content from old systems are fully migrated (3 years after it's been 'retired' our twiki is still the best place to go for some things). This is hard - it's rarely budgeted, and involves tedious and/or impossible work.

I suspect it's impossible to have a single system that will manage all your institutional knowledge -- I know many people are working on solving this from both directions, but I don't believe there's anything suitable now.

Whatever you choose it needs to have a low cost of entry for non-technical staff to update, while not frustrating your technical types. This is hard to find.

In 2007 I set up DekiWiki (based on mediawiki, but since abandoned) for a medium-sized gov agency -- in 2013 when I caught up with that team I was surprised they were still running it. It was internal only, so they weren't so worried about lack of patches, and they hadn't found anything better in the interim.

Out of that experience I'd suggest that whatever you do go with, make sure it's easy to extract your data, and that you maintain your own full copies of product documentation just in case the product is abandoned. Also - don't assume products won't be abandoned. MindTouch / Dekiwiki [1] was big in the mid 2000's.

[1] https://en.wikipedia.org/wiki/MindTouch

Reply on news.ycombinator.com