OpenScienceMOOC/Module-5-Open-Research-Software-and-Open-Source

Content: writing good documentations

Remi-Gau opened this issue · 8 comments

Remi-Gau commented

In line with issue #29, this came across my twitter line and made me realize that, unless I have overlooked it, I have not seen anything yet in the MOOC about writing documentation (what it entails and what guidelines to follow, what tools might exist).

Is that something worth considering or adding?

Was not sure whether it was more adated to this module or to module 3

Protohedgehog commented

That's a good idea! Do you mean things like good README files? We have a bit of that in the first Task, but it could perhaps be expanded on there?

schlauch commented

I think that this is a good point. In addition, the README is the first impression that you make and it is a kind of light-weight documentation artifact. I found some examples of how to structure READMEs here: https://github.com/matiassingers/awesome-readme#tools

  • 👍1
Protohedgehog commented

I've already included some information here on how to write a good README file. But please do expand on it if you think it can be improved! @Remi-Gau @schlauch :)

Protohedgehog commented

Pinging @Remi-Gau and @schlauch - do you think this is okay for now, so I can close this issue, or still room for improvement? :)

schlauch commented

Yes, I think that task 1 already does a good Job explaining the basic aspects :)

Protohedgehog commented

OK, will wait for @Remi-Gau to have a look before closing this - thank you!!

Remi-Gau commented

I think it is better to close the issue for now. I had some other ideas but most of them are too raw, halfbaked and generally disorganized that I can write them down.
I might reopen it later and or directly send a PR once I got it sorted.

  • 👍2
Protohedgehog commented

OK, sweet, thanks @Remi-Gau! Would be sweet to get back on this as your thoughts develop, but I think we at least have the basics covered for now :)