search

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

Module 5: Open Research Software and Open Source
https://eliademy.com/catalog/oer/module-5-open-research-software-and-open-source.html
MIT License
73 stars 52 forks source link

Content: writing good documentations #43

Closed Remi-Gau closed 5 years ago

Remi-Gau commented 5 years ago

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 5 years ago

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 5 years ago

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

Protohedgehog commented 5 years ago

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 5 years ago

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 5 years ago

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

Protohedgehog commented 5 years ago

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

Remi-Gau commented 5 years ago

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.

Protohedgehog commented 5 years ago

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 :)