search

smiths / caseStudies

Case studies of (manual) documentation for scientific computing software
3 stars 2 forks source link

SSP MIS Revisions #217

Closed bmaclach closed 5 years ago

bmaclach commented 5 years ago

The MIS for SSP is ready for review, @smiths.

@Malavika-Srinivasan for your review, please look at the version of the document on the ssp_MIS branch.

Malavika-Srinivasan commented 5 years ago

Hi @bmaclach ,

Thank you for the notification. Please see my document at ,

https://github.com/Malavika-Srinivasan/CAS741/tree/master/docs/Design

Thanks, Malavika

smiths commented 5 years ago

Comments on the revision of the MIS are given in 74f04a4.

bmaclach commented 5 years ago

Thanks @smiths. I've addressed some of the comments and asked follow-up questions to others here: 8d8f5904378e4329f73967ab2811edd8f8bb927c

smiths commented 5 years ago

@bmaclach, I'll review this work when I review the final documentation.

bmaclach commented 5 years ago

Okay @smiths, but if you don't mind, there was one question I hoped to get an answer to before submitting the final documentation. You suggested creating a module specifically for exporting types. I can do this, but I hesitate because I used the types in the MIS to make the MIS more readable, but the types do not actually exist in the implementation. Would it be okay to have a module that is not actually implemented by anything? Or perhaps somewhere in the MIS (the notation section, maybe) I can say something like "Throughout this document, 'coord' is used as shorthand for the type 'tuple of (x, y : R)'" and likewise for the other types?

smiths commented 5 years ago

Okay, I understand now. I was reading the types as if they were exported. If you relabel the sections where you introduce types as "local types" this will avoid confusion and let you use the types as you intended.

bmaclach commented 5 years ago

All right, thanks for the suggestion.

smiths commented 5 years ago

@bmaclach, I merged the final documentation. Are the changes in this branch still necessary?

bmaclach commented 5 years ago

@smiths These changes were merged in with the final documentation.

smiths commented 5 years ago

@bmaclach, great to hear that the changes were merged. Therefore, I will close this pull request. If there is no new information in this branch, please go ahead and delete it, so that we don't need to wonder about it again in the future.