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

11–20 of 93 posts

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

#11

Post by andygcook »

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.

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

#12

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

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

#13

Post by pedrorijo91 »

dalemyers wrote: post #9
sz4kerto wrote: post #8

Earlier quoted context omitted.

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

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

#14

Post by [deleted] »

dalemyers wrote: post #9
sz4kerto wrote: post #8

Earlier quoted context omitted.

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.

[deleted]

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

#15

Post by ravitation »

dalemyers wrote: post #9
sz4kerto wrote: post #8

Earlier quoted context omitted.

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.

Away from Confluence and to the documentation directories?

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

#17

Post by clintonb »

dalemyers wrote: post #3
iamNumber4 wrote: post #2

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

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…

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

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

#18

Post by timlloyd »

dalemyers wrote: post #3
iamNumber4 wrote: post #2

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

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…

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.

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

#19

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

Post reply on HN