3 ms·

Here's what I did on my previous team to encourage writing and documenting while keeping the barrier low: use the internal/team blog feature in Confluence. I ha

Here's what I did on my previous team to encourage writing and documenting while keeping the barrier low: use the internal/team blog feature in Confluence. I had a team of 5 so posting to that blog did not "spam" a lot of people, and you had to watch the "space" to get notifications at all. I encouraged the team to write blog posts on anything they didn't know and took time to figure out, or if they stepped through a process for the first time that wasn't already documented, or ran into some dev VM issue that they fixed. Crucially, I made clear that a "blog post" could be as little as 1 paragraph and a code snippet, it didn't have to be big. Blogging had the following advantages: 1. No need to think of "where to put this in the wiki" – just write it in the blog & if we decide to put it in wiki we can move it later 2. Blog posts naturally "go away" over time, so it's clear that something written a year ago might not be current 3. It was regular writing practice for everyone on the team 4. It allowed others on the team to learn from someone's experience & improved information sharing & collaboration 5. If I figured out how to solve some issue and someone else ran into it, I could say "go look at this blog post" 6. When we had a new person join the team, during orientation I'd say "read the last 6 months of blog posts (might take an hour or two) and that helps them understand the team culture & norms way faster than they would otherwise 7. It gave me (team lead) more visibility into what people were doing & allowed me to step in and help when appropriate. 8. It "forced" people to structure their thinking & clearly define the problem they were facing and the solution 9. It allowed people to "get credit for" work that might otherwise be invisible (e.g. spending a day debugging some webpack issue or researching options for an upcoming feature). Over a year or so this became a major part of our team's practices, and there were countless times when someone on or off our team would say "how do I do X" or "why did you chose to do Y" and I'd say "good question! Go read this blog post." Currently I have google suite instead of confluence and I seriously miss the blog feature. If someone knows a good, small, private (not public but easy to share internally) "team blog" platform, let me know. (I tried blogger but sharing is a pain in the butt.)

emilecantin 6y ago
A simple, dev-centric solution could be simply a Gatsby or Jekyll blog on a private repo. You can have your team members clone it & run on their own machine (easy but "hackish"), but I think it's actually possible to restrict access to team members on a published GitLab pages.
Viliam1234 6y ago
What are the blog features you actually need? If instead you used a wiki (e.g. MediaWiki), with the convention that all blog articles are prefixed by "YYYY-MM-DD USERNAME" and linked from the top of the "All Articles" page, what functionality you want would be missing?
- sequoia 6y ago
  Hm that sounds like a good solution. It's a bit more friction as I must ask people to make sure they follow a specific format (and don't forget to add it to the index page!!) rather than just clicking "new post" button and it doesn't have a "small team/space" feature like in Confluence, but it could work. These may seem like very small hurdles, but when you're asking people to do something they might not do on their own, every little bit of friction makes it less likely they'll actually do it, or more likely they'll be frustrated & resentful if you insist they do it. I do like the date metadata & sorting from a blog like wordpress or confluence: automatic grouping by year, automatic ordering, as well as features like tags etc.
simonw 6y ago
A absolutely love the concept of internal blogging. Writing documentation has a barrier to entry: what if I'm wrong? What if others on my team disagree with how I'm documenting this? What if I'm on the hook for maintaining this documentation for the rest of my career? Or what if the documentation goes out-of-date and ends up causing more harm than good? Blogs solve all of these. If I post an internal blog about how something works it has three things that fix this: 1. It has a date on it. It's clear that it may not still be up-to-date in a few years time. 2. It has my name on it. It's clear that this is my opinion / my experience at the time, not the official internal position of the company 3. It's a "blog", not documentation - so it's OK if it's incomplete or inaccurate. I ran an internal personal blog at my last employer for this reason - using Confluence because we already had it, so I didn't need to introduce a new tool. I didn't quite manage to make it stick as a habit for other engineers - I'd have liked to invest more effort in that.

emilecantin 6y ago

A simple, dev-centric solution could be simply a Gatsby or Jekyll blog on a private repo. You can have your team members clone it & run on their own machine (easy but "hackish"), but I think it's actually possible to restrict access to team members on a published GitLab pages.

Viliam1234 6y ago

What are the blog features you actually need? If instead you used a wiki (e.g. MediaWiki), with the convention that all blog articles are prefixed by "YYYY-MM-DD USERNAME" and linked from the top of the "All Articles" page, what functionality you want would be missing?

sequoia 6y ago
Hm that sounds like a good solution. It's a bit more friction as I must ask people to make sure they follow a specific format (and don't forget to add it to the index page!!) rather than just clicking "new post" button and it doesn't have a "small team/space" feature like in Confluence, but it could work. These may seem like very small hurdles, but when you're asking people to do something they might not do on their own, every little bit of friction makes it less likely they'll actually do it, or more likely they'll be frustrated & resentful if you insist they do it. I do like the date metadata & sorting from a blog like wordpress or confluence: automatic grouping by year, automatic ordering, as well as features like tags etc.

simonw 6y ago

A absolutely love the concept of internal blogging. Writing documentation has a barrier to entry: what if I'm wrong? What if others on my team disagree with how I'm documenting this? What if I'm on the hook for maintaining this documentation for the rest of my career? Or what if the documentation goes out-of-date and ends up causing more harm than good? Blogs solve all of these. If I post an internal blog about how something works it has three things that fix this: 1. It has a date on it. It's clear that it may not still be up-to-date in a few years time. 2. It has my name on it. It's clear that this is my opinion / my experience at the time, not the official internal position of the company 3. It's a "blog", not documentation - so it's OK if it's incomplete or inaccurate. I ran an internal personal blog at my last employer for this reason - using Confluence because we already had it, so I didn't need to introduce a new tool. I didn't quite manage to make it stick as a habit for other engineers - I'd have liked to invest more effort in that.