Ask HN: How does your team handle knowledge documentation?
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?
[+] [-] ryanmonroe|8 years ago|reply
[+] [-] ajeet_dhaliwal|8 years ago|reply
[+] [-] Balgair|8 years ago|reply
[+] [-] dsnuh|8 years ago|reply
[+] [-] swyx|8 years ago|reply
[+] [-] reducesuffering|8 years ago|reply
[+] [-] iandanforth|8 years ago|reply
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|8 years ago|reply
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.
[+] [-] maxxxxx|8 years ago|reply
[+] [-] tarr11|8 years ago|reply
I really never thought of actually having a person responsible for internal corporate knowledge, but it makes a lot of sense!
[+] [-] clintonb|8 years ago|reply
At edX we have information spread between Confluence and Google Drive. Search is not ideal for either. Information sharing is not great.
[+] [-] jhchen|8 years ago|reply
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|8 years ago|reply
[+] [-] rubidium|8 years ago|reply
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|8 years ago|reply
[+] [-] iamNumber4|8 years ago|reply
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|8 years ago|reply
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.
[+] [-] throwayit|8 years ago|reply
* 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|8 years ago|reply
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|8 years ago|reply
[+] [-] billconan|8 years ago|reply
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|8 years ago|reply
* 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.
[+] [-] 2muchcoffeeman|8 years ago|reply
[+] [-] anotheryou|8 years ago|reply
- 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)
[+] [-] bbarn|8 years ago|reply
[+] [-] wila|8 years ago|reply
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.
[+] [-] wink|8 years ago|reply
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|8 years ago|reply
[+] [-] mabbo|8 years ago|reply
I was about to make this same joke. Glad to hear that everyone is just as screwed on this.
[+] [-] dsr_|8 years ago|reply
reads markdown
has an online editor available
stores in git
and is searchable.
[+] [-] pedrorijo91|8 years ago|reply
[+] [-] sz4kerto|8 years ago|reply
Confluence is a very good wiki. There's no wiki that creates good structures for you automagically.
[+] [-] waibelp|8 years ago|reply
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).
[+] [-] maxxxxx|8 years ago|reply
[+] [-] ifoundthetao|8 years ago|reply
And Slate was just a pleasure to work with.
[+] [-] bastijn|8 years ago|reply
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.
[+] [-] vijaykodam|8 years ago|reply
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.
[+] [-] thisisit|8 years ago|reply
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|8 years ago|reply
[+] [-] gtf21|8 years ago|reply
* 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
[+] [-] dalemyers|8 years ago|reply
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|8 years ago|reply
[+] [-] helpsite|8 years ago|reply
[1] https://helpsite.io
[+] [-] allan_s|8 years ago|reply
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,
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|8 years ago|reply
- 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.