Re:Ask HN: How does your team handle knowledge documentation?
by throwayit on Monday November 06, 2017 @06:25PM
(#15639890)
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.
* 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.