search

smiths / caseStudies

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

SolarHeatingWaterOnly_MIS: Incorrect Documentation #56

Closed elwazana closed 6 years ago

elwazana commented 6 years ago

The MIS document in SolarHeatingWaterOnly has the incorrect document, the document currently there has incorporated PCM, which is from the SWHS repository.

elwazana commented 6 years ago

0f4f403445fab607ae5b6d767fc19dd271a45a7f

JacquesCarette commented 6 years ago

@elwazana the commit you link to just changes the PDF -- which isn't the interesting change. You should link the one where the source was changed. And check in the source and PDF together.

elwazana commented 6 years ago

37229a7bbe9a2af212336ed8e5231416689e316d

This is the correct one then, however, the name of the file was incorrect so I changed that as well whcih seems to cause git to have highlighted the whole file as being changed. Only line 34 was edited, specifically the title from "Module Guide for Solar Water Heating Systems Incorporating Phase Change Material" to just "Module Guide for Solar Water Heating Systems"

I couldn't find any other mention of PCMs in the file outside of the title.

smiths commented 6 years ago

I agree that the new Module Guide no longer is connected to the PCM version (SWHS). Having a quick review of the noPCM example did get me thinking about how the differences between SWHS and noPCM could be increased. The noPCM version doesn't really need an ODE solver. So that we don't forget this example in the future, I created an issue in the Drasil repo, labeled FutureDesignVariability. I think we will be able to think of more examples under this label, which will come in handy when we tackle the design language. @JacquesCarette, if you think there is a better place to record ideas like this, please let me know.

The new Drasil issues is at:

https://github.com/JacquesCarette/Drasil/issues/492

JacquesCarette commented 6 years ago

I agree that issues may not be the optimal place to store such ideas. But we haven't used the wiki much, so that may be a way to bury it instead! We might need to explore the features of github some more, including the various plug-ins, to see. In the meantime, an issue will at least mean that it won't get lost. At least, unless the number of (open) issues keeps climbing at the current rate!

smiths commented 6 years ago

Using labels for the issues helps, but I agree that at some point there will be so many issues that we'll still have a problem of management. Hopefully we can start closing issues at a rate close to the rate of issue creation. 😄