
Ask HN: How does your team handle knowledge documentation? - dalemyers
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&#x27;t too much of a challenge, it&#x27;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.<p>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&amp;A. &quot;I&#x27;m having issue X, how do I fix it?&quot; Think StackOverflow.<p>So, what does your team do for these challenges? How effective is your solution? What do you think would be better?
======
ryanmonroe
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.

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

------
iandanforth
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.

~~~
Viliam1234
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.

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

------
clintonb
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.

------
jhchen
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.

~~~
alxndr13
what is the company called you founded?

~~~
jhchen
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.

~~~
billconan
How is your solution different?

~~~
jhchen
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.

------
rubidium
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.

~~~
throwayit
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.

------
iamNumber4
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!

~~~
dalemyers
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.

~~~
timlloyd
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.

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

~~~
timlloyd
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](http://www.mkdocs.org) [2]
[https://lunrjs.com](https://lunrjs.com) [3]
[https://squidfunk.github.io/mkdocs-
material/](https://squidfunk.github.io/mkdocs-material/)

------
throwayit
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.

------
bastijn
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.

~~~
xaedes
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!

~~~
bastijn
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/](https://squidfunk.github.io/mkdocs-material/)

~~~
xaedes
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.

------
billconan
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.

~~~
avn2109
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.

~~~
dalemyers
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.

------
wink
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.

~~~
dalemyers
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.

~~~
JCharante
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](https://github.com/blog/2219-search-wiki-pages)).

~~~
wink
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.

------
pedrorijo91
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...

~~~
sz4kerto
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.

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

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

------
ifoundthetao
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.

~~~
bastijn
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.

~~~
Ninjaneered
Did you ever try Elasticsearch on your MediaWiki instance?

------
vijaykodam
If you want to maintain documentation for different versions of the same
software then consider AsciiBinder.
[http://asciibinder.org/](http://asciibinder.org/)

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

There is Mkdocs ([http://www.mkdocs.org/](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.

------
thisisit
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.

------
kusmi
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.

------
gtf21
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](https://news.ycombinator.com/item?id=12540678)
[2]: [https://discourse.org](https://discourse.org)

~~~
dalemyers
>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".

------
flarg
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!

------
helpsite
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](https://helpsite.io)

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

------
hv23
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.

------
marpstar
We use Jingo
([https://github.com/claudioc/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.

------
cableshaft
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).

------
melissam
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).

------
Jeff_Brown
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](https://github.com/synchrony/smsn/wiki)

------
Ninjaneered
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.

------
PeOe
Hey, I can recommend [https://zenkit.com](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.

------
andygcook
Andy from Tettra here with some shameless self promotion:

My startup is actually working on this exact problem:
[https://tettra.co](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.

~~~
bastijn
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.

~~~
andygcook
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

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

------
dmuth
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.

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

------
thomasswilliams
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-...](https://github.com/thomasswilliams/RigorousSearch-MediaWiki-
extension-updated-for-MediaWiki-1.28)

------
oschn
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](https://teamemo.com)) because
knowledge management should be easy, fast and fun.

~~~
Ninjaneered
Did you try MediaWiki's Visual Editor?

------
tschlossmacher
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!

------
omerg
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](http://mindflowai.com)

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

~~~
dalemyers
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.

------
rwc
Nuclino has been a winner for us.

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

------
bpyne
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.

------
akrymski
Anybody tried Dropbox Paper?

------
Jedd
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](https://en.wikipedia.org/wiki/MindTouch)

