Feedback on README for Dataverse
pdurbin opened this issue · 6 comments
Hi! I just stumbled upon "maker of @feedmereadmes" at https://twitter.com/LauritaApplez and think it's a great idea to encourage projects to give and receive feedback on READMEs. I'm especially interested in the README maturity model you've come up with.
From what I understand I'm supposed to create an issue and link to my project's README and ask for feedback. Please take a look at the README at https://github.com/IQSS/dataverse and let me know what you think! Thanks!
(I wish I had know about Feedmereadmes before today because I just gave a talk last week about open source and would have mentioned it!)
Thanks for the note, @pdurbin. Will take a look ASAP. :)
Hi @pdurbin: Finally had a chance to look. Seems like you've created a comprehensive set of docs for the project, so you might want to go light on the README but structure it a bit more with section headers and a quickstart. Take a look at this template and see if you think it makes sense to copy/paste parts of your docs into the README file, covering these bases at a very high level:
https://github.com/zalando/zalando-howto-open-source/blob/master/READMEtemplate.md
Dataverse documentation writer checking in here - Thanks for the feedback on our readme! The example you link is a great resource. It's helpful how it enumerates the various questions a good readme answers.
I agree that we don't want to make our readme too heavy considering how comprehensive our docs are. I'm considering bolding key terms in our readme to help draw the reader's eye to the bits that are most relevant to them.
@LappleApple thanks for taking a look! You seem to be saying the Dataverse README isn't bad but perhaps could use headings as in the Zalando template and maybe a quickstart. As @dlmurphy indicated, we might start just by putting a few phrases here and there in bold.
Yes, I'm into comprehensive documentation (but there's more we could do). Here's some of what I said in the talk I mentioned above:
According to the same GitHub survey, 93 percent of people reported being frustrated with incomplete or confusing documentation. You can read about this in an article on The Next Web by Matthew Hughes with the title "Free software is suffering because coders don't know how to write documentation".
There's an article by Jeff Atwood of Stackoverflow fame entitled, "If it isn't documented, it doesn't exist".
You should consider writing executable documentation for your Installation Guide. Add a Vagrantfile to the root of your git repo. Explain that if you type
vagrant up
, you can get a working installation that you can kick the tires on. Sysadmins will go look at your Vagrant scripts to see what you did to get a working system and reverse engineer whatever they need to apply it to their configuration management systems. You can also use your documentation in tests. If you document what JSON to send to your API, put it in your API guide and then execute integration tests using that JSON.
I also enjoyed your tweet the other day about the importance of docs.
Thanks!
@pdurbin I use the same GitHub survey stat about docs in my talks. :)
@LappleApple thanks again for the feedback. I don't see any reason to leave this issue open so I'm going to close it but I wanted to let you know that I'm still spreading the word about feedmereadmes such as at publiclab/plots2#2793