| > Document how to build and run it. This, especially in non-web repos (C/C++) is common mistake of READMEs and docs. Let's take an example of XFCE-WM project [0]. The main README does not include any information how to compile it, nor provides any link to the documentation how to build this very specific code. If you will google it you might find following wiki page [1], which is general for all repositories. In the COMPOSITOR [2] file you might notice some information about flags that you can provide during building, and that's great such doc has been created, but except that document I couldn't find any information how "fresh contributor" would like to debug and test some change in code that he made in the cloned repository. Download and install some linux distro on virtual machine and then invest (1h+) to configure it accordingly to run it there? Use Xephyr (I guess "fresh contributor" has never heard about this tool)? In my honest experience, the "how to build" step is probably included in many of repositories, but the "how-to-run" is usually lacking in READMEs and it is what I really would like to see in complex projects (e.g. desktop environment). > Document your availability. If you have to step away from the project, put this at the top of the README, even if it's temporary. Don't drip-feed interaction - be either on or off. One more thing related to docs and "how-to-build-&-run" thing. Let's say the project owner have some critical accident that made him unavailable to push progress of development forward for few months or longer. If there isn't any knowledge shared (docs, other contributors) then I guess the project will be stalled and possibly forgotten if there is no clear incentive to use alternative methods of repo maintenance (e.g. fork). [0]: https://github.com/xfce-mirror/xfwm4 [1]: https://docs.xfce.org/xfce/building [2]: https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR [3]: https://en.wikipedia.org/wiki/Xephyr |