Fantastic article. I recently did some research for a presentation about open source docs and here were some key takeaways. Some are much in line with your suggestions. The readme was equally as important as the website.
And some more developer specific ones were that 1) you can just publish the readme also as the website as a MVP with one click from github 2) that wiki's were a waste of time 3) you should pay close attention to he content of the readme as well as making sure it is accessible.
The github page for the event has more info on good documentation practices, but also tries to apply them in github as well.
So the counterpoint in my daily consulting work is that the reality can be far from these ideals. One thing that is nice about open source is it gives you a way to practice best practices out in the open and gain experience and feedback. And sometimes it is about looking for small wins that will help the team short, medium and long term. Rather than some large rewrite.
Try to avoid the no docs / just read the code mentality. Use the "what if person x got hit by a bus" reasoning to try to create a way that the basics of the operation can be restarted and built upon. This will help not only in an emergency situation, but also onboarding new developers, increasing visibility with stakeholders, and allowing others on the team (for example designers) to deepen their understanding of the project.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Fantastic article. I recently did some research for a presentation about open source docs and here were some key takeaways. Some are much in line with your suggestions. The readme was equally as important as the website.
And some more developer specific ones were that 1) you can just publish the readme also as the website as a MVP with one click from github 2) that wiki's were a waste of time 3) you should pay close attention to he content of the readme as well as making sure it is accessible.
The github page for the event has more info on good documentation practices, but also tries to apply them in github as well.
So the counterpoint in my daily consulting work is that the reality can be far from these ideals. One thing that is nice about open source is it gives you a way to practice best practices out in the open and gain experience and feedback. And sometimes it is about looking for small wins that will help the team short, medium and long term. Rather than some large rewrite.
Try to avoid the no docs / just read the code mentality. Use the "what if person x got hit by a bus" reasoning to try to create a way that the basics of the operation can be restarted and built upon. This will help not only in an emergency situation, but also onboarding new developers, increasing visibility with stakeholders, and allowing others on the team (for example designers) to deepen their understanding of the project.