Why GitHub Issues > documentation
Answer: Because they're append-only while documentation is shared-state.
Disclaimer: I'm not using GitHub Issues at the moment at my job.
Hearing append-only vs shared-state should probably convince most distributed-systems/functional-programming/event-sourcing people, of whom I'm not one. But let's break that down a little bit.
In documentation, to make a change, you're stepping on your team's feet. You could be editing, or even deleting, their work. Thus, you all must achieve consensus on what the state of the documentation should be.
While such consensus's cost and probability of rejecting good updates may be acceptable for code for the benefit of rejecting harmful ones, it isn't for documentation. Even more, in documentation, you want all knowledge and thoughts to be written down.
Contrast that with GitHub Issues or any append-only communication tool: To make an edit, you just add a new issue or comment. The issue or comment is yours and you're the only one responsible for it. You don't need to take other people's opinions. (Granted, there must be some standards for communication in a team, ... etc.)
Also, in documentation, you need to consider how your edit fits in the whole because a reader will only read the current state. With GitHub Issues, when you write a comment, a reader sees both your comment and other members' comments.
Even more, there're other nice features in GitHub Issues or one that I find very crucial: automatic back-linking. Disagree with an issue X and/or find that it's outdated/wrong? ... Just link to it in your new issue Y and readers of X will see that issue Y references it! ... They can then click on the link and go read Y and find your correction/update.
A prerequisite to all this: Don't use GitHub Issues just for issues. Use it as a forum. And talk freely. You can always close the issues for which you couldn't reach a solution/"no plans to fix" -- but you'd have gained the benefit of documenting your thought processes for future team members.
Some other cool things about GitHub Issues:
- Closeability. That's the #1 reason I like it to, e.g., Slack Threads. Reduces mental load.
- Automatic back-linking. Talked about it above.
- Simple/Clean/The textbox's width is not too big: This might seem like a minor point, but that's the main reason I prefer it to, e.g., GitLab Issues. But GitLab Issues is also good (but I really dislike its UI. Too crowded. Sorry).
Some brag. An issue of mine of which I'm proud: https://github.com/tailwindcss/tailwindcss/issues/840 ... Yes, the solution is no solution but we documented the possible workarounds and/or why there's no solution (not me, Tailwind CSS's developer 😂 )
Disclaimers
- Please, think for yourself what's better for you. And as I've told you, I'm not using it at a real project at the moment. Actually, I don't think I ever have. And there could be cons I don't know of that you can discover with experience. For example, I dislike having to enter a title for an issue and their right-to-left support is not so good, I think.
- In general: I'm not responsible for anything in this article. Read on your own risk.
Privacy notes
- Buttondown tracks who opens, clicks, or forwards my emails, and shares this data with me. If you want to delete this data, email me and I'll try my best!
- Buttondown adds "UTM sources" to my links to let websites I've linked to know that the source of the new traffic is my newsletter (as far as I understand).
- Buttondown gives me the choice to opt out of both points above, but I've chosen to opt in.
Copyright
This is an All-Rights Reserved work. Please, don't rehost it.
Linking to it is naturally allowed (and appreciated!), but rehosting is not. Reasonable sharing like forwarding to a few friends or a quote screenshot is fair use, I believe.
You can reply directly to this email.