Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC / COM: add a "Design documents" section in the docs #805

Open
fmaussion opened this issue Jun 19, 2019 · 5 comments

Comments

Projects
None yet
2 participants
@fmaussion
Copy link
Member

commented Jun 19, 2019

Idea by @DavidParkes today at the workshop - TBD later

@fmaussion fmaussion changed the title DOC / COM: add a "Design documents" DOC / COM: add a "Design documents" section in the docs Jun 19, 2019

@DavidParkes

This comment has been minimized.

Copy link

commented Jun 26, 2019

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!

@DavidParkes

This comment has been minimized.

Copy link

commented Jun 26, 2019

The obvious questions are then a) What format do these take? and b) Who is responsible for writing them?

@fmaussion

This comment has been minimized.

Copy link
Member Author

commented Jun 26, 2019

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:

a) What format do these take?

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

b) Who is responsible for writing them?

We are! I'm happy to help of course, but we should all feel responsible to write and maintain them!

@DavidParkes

This comment has been minimized.

Copy link

commented Jun 27, 2019

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.

@fmaussion

This comment has been minimized.

Copy link
Member Author

commented Jun 28, 2019

@DavidParkes a WIP is here: https://docs.oggm.org/en/latest/oeps.html - you can add your contribution whenever suits you. One good thing would be to write the intro (TODO on this page). I can guide you through the structure if needed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.