Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
DOC / COM: add a "Design documents" section in the docs #805
Some explanation for the idea and write-up of what was discussed:
At present there is documentation for what OGGM already does, issues raised to fix specific problems or add particular, well-defined small features, and discussion on slack channels about progress in various aspects of the model, but what is currently lacking is a detailed record of what is planned for OGGM's future features. By adding design documents - docs which describe a specific goal for OGGM, what will be implemented to reach it, the scientific justification (if needed) and (if possible) an outline of how the code will change (particularly focusing on things like where the task will fit in the workflow and what interfaces any new major functions will have) - we can let everyone see how things are progressing. We can also optionally list people associated with that aspect of model development (for example, Bea on a page for the developing parameterisation of calving) so that people can see who to talk to if they have an interest in working on a particular part of the model.
As mentioned when we discussed this, it is also a good way to show what isn't being developed right now; for someone interested in whether the model will be able to do something it currently doesn't, it makes it easier to be able to either point to a specific document about what they're interested in, or to say conclusively that it hasn't progressed beyond a more general idea (or the third option of it being better developed but no doc existing, which should be a motivation to write the doc).
An additional benefit is making it easier to bring new people into working on OGGM. If the design docs are sufficiently detailed (this would take time, going from initial versions which are more manifestos about change in certain features to have specific comments about how to code them) then anyone joining the project can much more quickly narrow down what they need to be looking at and have a lot of direction in implementing changes. Of course, it takes significant time to write the docs in that level of detail, but I think it's an overall saving. Even if the person writing the detail in the doc ends up being the one to code the final changes, it's still valuable to have the design process documented (especially if there's a lag between the design and getting round to the code) and for poorly-disciplined people like me it would make me adopt a better approach to designing it!
I like the idea very much, thanks a lot for bringing this up! I agree with your analysis.
Following the python way of doing things, these design documents could be called "OEP", for "OGGM Enhancement Proposals" - sounds a bit weird, but fun. The other acronym would be "ODC" for "OGGM Design Documents". Any preference?
Regarding your questions:
I think they should live on github to allow collaborative editing and review - and give them a history and visibility. I suggest to use the rst format and build them in the documentation (like numpy: docs and NEPs
We are! I'm happy to help of course, but we should all feel responsible to write and maintain them!
I quite like the Enhancement Proposals terminology. It's a slightly more focused term than 'design documents', and I think that's what we're really looking at here; documenting desired changes which actually meaningfully improve what OGGM is capable of. It also illustrates another potential use for these sorts of documents: research proposals! I can't speak from experience but I imagine it must be beneficial to be able to point to some detailed design work independent of the project proposal itself when applying for things like PhD and postdoc funding for work that would relate to enhancing certain aspects of the model.
The collaborative aspect is definitely important. I guess the first step in providing an idea of the written format would be to construct a template/guide to what should be included (like in the 'meta-NEPs' in your link). That's something I'd be happy enough to put together a draft (and it might even be beneficial to come from more of a user than a developer perspective).
I suppose on responsibilities I was thinking more specifically about people working on what seem like natural enhancements already. I'm conscious it feels like putting the onus on, say, Anton to write a proposal on surface energy balance and Bea to write a proposal on calving.