Each engineer knowledge is endlessly valuable, and I'm searching for a way to make all those hours spent on problems profitable by disseminating them amongs a growing team of ~15 software engineers.
We already have countless ways to do so:
- internal brown-bag lunches (BBL)
- a lot of blog posts
- regular hackdays with a demo to the team at the end
- local meetups, etc
But we needs to formalize this knowledge into a base that is easily searchable, discoverable, and easy to feed.
We've heard of Stack Overflow for Teams, also considering to open a Notion.
What do you recommend?
Top comments (21)
Wiki.
I find a WIKI the best... but not some crappy confluence or any other sort of hard to use wiki I would suggest a PLAIN and simple wiki. If you are already on gitlab ... its wiki is enough .. or MediaWiki
Agreed, although I'm just starting to get familiar with Confluence. Microsoft Teams also (can) have a wiki for each channel.
Confluence is fine if someone has configured it correctly but it costs a lot :)) If you have it :) great ;)
You could use a opensource alternative named XWiki (in a lot of ways, very similiar to Confluence).
I've been using it for the past 7 years and been quite happy :)
yes used it as well :) however I actually written it in my initial comment but then I removed it because it is a bit harder to setup :+)
Having done it a few times and documenting the process, I wouldn't say it's hard. But their docs regarding setting it up could use some improvement 🙂
As soon as I take the time and finish my step-by-step guide for it, I will try to update the official docs on it as well 🙂
great ;P for the next job :D:D I might try to setup xwiki again :D:D:D
How do you organize all the content in that wiki?
Per project, per tech, per category?
Also, I'm not sure we can add multiple tags on wiki pages. And what about the search features?
Organization of content usually for us is like this
We do not use tags, because I find tags harder to use. In many cases the search is perfect, however if not since I do have the WIKI itself on my local file system (e.g. when using gitlab wiki (in my current company) I can also do a "find ." :) I find it even faster then a web interface but I am a bit console guy.
We've just started using Notion... I think in the end it's going to be really valuable but it takes a little while for everyone to make using it a habit!
It's perfect for techy teams as you can use trello-like layouts, embed code samples, write in Markdown... All the stuff we tend to be familiar with already.
For us Notion is particularly useful as not only can you easily share notes, links, code examples etc across the team, but it also lets you quickly generate a PDF of the content which you can add to Jira tickets / send to clients, etc, which is so handy!
There really isn't any Markdown in Notion. Just some shortcuts that remind of Markdown. You can't import/export Markdown and get proper Notion pages.
I've been able to both import and export Markdown into/from Notion... All of my Dev posts start life in Notion 🤷♀️
But yep what I mean most of all is the shortcuts, so you can write as you would a Markdown file, eg to create headers, links, format text etc.
Some have mentioned Confluence here, or some other wiki. Having done my fair share in the CMS world, here are some suggestion/comments:
You will find MANY online blog posts or comments that basically say "Confluence is where documents go to die". However, this is not the tools fault, but rather the implementation and ongoing maintenance.
if you have a small team, develop a consistent category and tagging methodology up front and try to stuck to it. Things can easily get out of control, and a search engine will not help.
If you can, develop some common templates for the documentation. This will ensure you have consistent information, and you can clearly see where you have gaps. This also allows other developers to jump in to fill the gaps where they can.
Documentation is not a replacement for comments in code. "just read the code" is a symptom of "cowboy coding" and doesn't help the overall team --especially if you add new people to the team.
If you use a documentation generator (Sphinx, Swagger, etc) be sure you actually add in all the annotations so there is more than just code examined. Explain WHY you did something, why the business logic is as it is, etc.
Write the documentation. Period. The person you are benefiting may be YOU six months down the road when you look back and forget what the heck you were thinking when you wrote that code.
Atlassian Confluence
Yep, it worked well when we had a project already pluged with the whole Atlassian suite, but we don't have that right know.
Thanks tho!
We use a couple solutions, stack overflow teams for our generalised question and answer portal, this helps with working on many different types of projects. And a notion esk (slite.com) wiki for our own internal project wikis.
We tried Stack Overflow for Teams for a couple of weeks. Our dev team consists of about 10 folks. It didn't gain traction at all.
Internal wiki's and functional documentation seems to work well. Because people aren't making a habit of just reading daily blogs, the content needs to be well-searchable for those times when we're wonder WTH is going on.
But really I think the best way to disseminate knowledge, especially business acumen, is via pair and mob programming.
Thanks for your feedback!
Confluence or any kind of Wiki is great. Even an internal blog, if you wan't something free. Blogger allows for free private blogs. The most important parts are ease of creating the content and searchability. I find Confluence aces the first, but fails at the second, for example.
I’ve used vue-press, Jekyll and Wordpress to build knowledge bases before. All have their pros and cons, but I would recommend Jekyll as it’s easy and quick to add pages and version control the content. You could try something like algolia to add a search but I haven’t used it myself.
We put a ton of stuff on internal OneNote notebooks. They function a lot like a wiki. They're very easy to author, add formatting to, attach files, and cross-link between pages. They have good search functionality too.