PLOS Rules for documenting scientific software

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

PLOS Rules for documenting scientific software

Tim Daly
https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561

1) Write comments as you code
2) Include examples and lots of them
3) Include a quickstart guide
4) Include a README file with basic information
5) Include a help command for command line interfaces
6) Version control your documentation
7) Fully document your application program interface
8) Use automated documentation tools
9) Write error messages that provide solutions or point to the documentation
10) Tell people how to cite your software

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: PLOS Rules for documenting scientific software

William Sit-3
Amen.

William

William Sit
Professor Emeritus
Department of Mathematics
The City College of The City University of New York
New York, NY 10031
homepage: wsit.ccny.cuny.edu

________________________________________
From: Axiom-developer <axiom-developer-bounces+wyscc=[hidden email]> on behalf of Tim Daly <[hidden email]>
Sent: Saturday, December 22, 2018 3:41 PM
To: axiom-dev
Subject: [Axiom-developer] PLOS Rules for documenting scientific software

https://urldefense.proofpoint.com/v2/url?u=https-3A__journals.plos.org_ploscompbiol_article-3Fid-3D10.1371_journal.pcbi.1006561&d=DwICAg&c=4NmamNZG3KTnUCoC6InoLJ6KV1tbVKrkZXHRwtIMGmo&r=qW9SUYRDo6sWEVPpx7wwWYZ79PdSWMRxNZvTih0Bkxc&m=oC0x0vQV9f5FuUNVQBO_UwV-h73cC7IliZkhPlVwAlw&s=47yINWjh8smzKAsgwzJnJsvhRj7LH22zTHA2D-1xPzA&e=

1) Write comments as you code
2) Include examples and lots of them
3) Include a quickstart guide
4) Include a README file with basic information
5) Include a help command for command line interfaces
6) Version control your documentation
7) Fully document your application program interface
8) Use automated documentation tools
9) Write error messages that provide solutions or point to the documentation
10) Tell people how to cite your software

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.nongnu.org_mailman_listinfo_axiom-2Ddeveloper&d=DwICAg&c=4NmamNZG3KTnUCoC6InoLJ6KV1tbVKrkZXHRwtIMGmo&r=qW9SUYRDo6sWEVPpx7wwWYZ79PdSWMRxNZvTih0Bkxc&m=oC0x0vQV9f5FuUNVQBO_UwV-h73cC7IliZkhPlVwAlw&s=GgpZ-fSxzeliAR6li7ywCwO46JNvaG84OVxPUx7mHKk&e=

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer
Reply | Threaded
Open this post in threaded view
|

Re: PLOS Rules for documenting scientific software

Tim Daly
I think one of the most important suggestions is the use of
a literature reference to the implemented algorithm. They
mention using DOI but any reference would do. I have tried
to figure out literature references to algorithms, some of
which decorate Axiom's current source tree. I wish there
were more.

Tim


On 12/22/18, William Sit <[hidden email]> wrote:

> Amen.
>
> William
>
> William Sit
> Professor Emeritus
> Department of Mathematics
> The City College of The City University of New York
> New York, NY 10031
> homepage: wsit.ccny.cuny.edu
>
> ________________________________________
> From: Axiom-developer
> <axiom-developer-bounces+wyscc=[hidden email]> on behalf of
> Tim Daly <[hidden email]>
> Sent: Saturday, December 22, 2018 3:41 PM
> To: axiom-dev
> Subject: [Axiom-developer] PLOS Rules for documenting scientific software
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__journals.plos.org_ploscompbiol_article-3Fid-3D10.1371_journal.pcbi.1006561&d=DwICAg&c=4NmamNZG3KTnUCoC6InoLJ6KV1tbVKrkZXHRwtIMGmo&r=qW9SUYRDo6sWEVPpx7wwWYZ79PdSWMRxNZvTih0Bkxc&m=oC0x0vQV9f5FuUNVQBO_UwV-h73cC7IliZkhPlVwAlw&s=47yINWjh8smzKAsgwzJnJsvhRj7LH22zTHA2D-1xPzA&e=
>
> 1) Write comments as you code
> 2) Include examples and lots of them
> 3) Include a quickstart guide
> 4) Include a README file with basic information
> 5) Include a help command for command line interfaces
> 6) Version control your documentation
> 7) Fully document your application program interface
> 8) Use automated documentation tools
> 9) Write error messages that provide solutions or point to the documentation
> 10) Tell people how to cite your software
>
> _______________________________________________
> Axiom-developer mailing list
> [hidden email]
> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.nongnu.org_mailman_listinfo_axiom-2Ddeveloper&d=DwICAg&c=4NmamNZG3KTnUCoC6InoLJ6KV1tbVKrkZXHRwtIMGmo&r=qW9SUYRDo6sWEVPpx7wwWYZ79PdSWMRxNZvTih0Bkxc&m=oC0x0vQV9f5FuUNVQBO_UwV-h73cC7IliZkhPlVwAlw&s=GgpZ-fSxzeliAR6li7ywCwO46JNvaG84OVxPUx7mHKk&e=
>

_______________________________________________
Axiom-developer mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/axiom-developer