Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How does your team handle knowledge documentation?

news.ycombinator.com

Post reply on HN
Print view View original

61–70 of 93 posts

Re: Ask HN: How does your team handle knowledge documentation?

#61

Post by swyx »

ryanmonroe wrote: post #25

I work at a large bank. Mostly people hold all relevant knowledge in their own head, and when they receive a request for information they only respond if their manager knows yours. Then, they will mostly refuse to create any type of actual document and instead request that you set up a meeting with them through Outlook. They are of course completely booked on their Outlook calendar for at least the next few weeks, an…

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.

Re: Ask HN: How does your team handle knowledge documentation?

#62

Post by Viliam1234 »

iandanforth wrote: post #29

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

Re: Ask HN: How does your team handle knowledge documentation?

#63

Post by 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

Re: Ask HN: How does your team handle knowledge documentation?

#64

Post by jhchen »

alxndr13 wrote: post #53
jhchen wrote: post #46

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

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.

Re: Ask HN: How does your team handle knowledge documentation?

#66

Post by 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

Re: Ask HN: How does your team handle knowledge documentation?

#67

Post by 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.

Re: Ask HN: How does your team handle knowledge documentation?

#68

Post by 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

Re: Ask HN: How does your team handle knowledge documentation?

#69

Post by throwayit »

rubidium wrote: post #10

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

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.

Re: Ask HN: How does your team handle knowledge documentation?

#70

Post by OJFord »

dalemyers wrote: post #28
clintonb wrote: post #17

Earlier quoted context omitted.

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?
Post reply on HN