New ask Hacker News story: Ask HN: How does your team keep informal documentation?
Ask HN: How does your team keep informal documentation?
3 by ravenstine | 2 comments on Hacker News.
My engineering team has been spending the day discussing how we want to improve our practices moving forward. A point that I brought up was that we could benefit from keeping what I refer to as "informal documentation" that is internal to our team (not org-wide), which I imagine as being just a place to share information that could be beneficial for the rest of the team. The reason I emphasize informality is that I've rarely seen more formal documentation work well at any company I've been at. Usually what happens is documentation is gatekeeped and the platform used is crummy. If I want to write an article on something I think is important, I should just be able to do it. For instance, if an engineer works on a project and develops some patterns or APIs they have a lot of knowledge about, they could write that information down for other developers in the future. My idea isn't to create elegantly structured documentation that should be guaranteed to be up to date, but to write notes or even record videos in an informal way, as if you're chatting with a fellow dev sitting next to you. There would be no gatekeeping; if any developer sees something they can improve or correct, they can do so without asking permission. My fellow team members seem to like this idea. However, I don't know what platform or tool would be ideal for this. Our company has Confluence, but I personally don't like it and most of the company doesn't like it. GitHub PR descriptions/threads somewhat fill that gap, but navigating this information can be difficult, and becomes more difficult the older a PR gets. How does your team achieve what I'm looking for? Does your solution work well? What is a tool or platform that you've found success with that you can recommend for this purpose?
3 by ravenstine | 2 comments on Hacker News.
My engineering team has been spending the day discussing how we want to improve our practices moving forward. A point that I brought up was that we could benefit from keeping what I refer to as "informal documentation" that is internal to our team (not org-wide), which I imagine as being just a place to share information that could be beneficial for the rest of the team. The reason I emphasize informality is that I've rarely seen more formal documentation work well at any company I've been at. Usually what happens is documentation is gatekeeped and the platform used is crummy. If I want to write an article on something I think is important, I should just be able to do it. For instance, if an engineer works on a project and develops some patterns or APIs they have a lot of knowledge about, they could write that information down for other developers in the future. My idea isn't to create elegantly structured documentation that should be guaranteed to be up to date, but to write notes or even record videos in an informal way, as if you're chatting with a fellow dev sitting next to you. There would be no gatekeeping; if any developer sees something they can improve or correct, they can do so without asking permission. My fellow team members seem to like this idea. However, I don't know what platform or tool would be ideal for this. Our company has Confluence, but I personally don't like it and most of the company doesn't like it. GitHub PR descriptions/threads somewhat fill that gap, but navigating this information can be difficult, and becomes more difficult the older a PR gets. How does your team achieve what I'm looking for? Does your solution work well? What is a tool or platform that you've found success with that you can recommend for this purpose?
Comments
Post a Comment