Conventions and documentation

Rothamsted-Ecoinformatics / farm_rothamsted

Custom farmOS features for Rothamsted Research.

GNU General Public License v2.0

6 stars 1 forks source link

Conventions and documentation #187

Open paul121 opened 2 years ago

paul121 commented 2 years ago

@aislinnpearson if you go to this repository's home page you will see I've started a README markdown file. Right now it is just a rough template of the features the farm_rothamsted module & submodule provides, but this could be expanded to further document the features and gotchas we've run into. Some ideas:

Add descriptions for each quick form (why they are needed, how they are used in specific workflows?)
Document the taxonomy hierarchies that must be configured for specific quick form(s)
Document the fields/metadata stored in experiment plans, treatment factors, plots, etc.

I'm going to assign this to you @aislinnpearson but no rush at all. I'm happy to help build this out, just think you would be best at adding the descriptions & background information about this project!

aislinnpearson commented 2 years ago

This is an excellent idea @paul121 - something that definitely needs to be done and which I have been putting off only because I'm not that proficient at markdown. I'll see how far I can get today with a few bits.

aislinnpearson commented 2 years ago

In the call with @paul121 today we agreed that we'd create a subfolder called 'docs' for documentation and in that folder create separate documentation for the Quick Forms and Experiment Module.

aislinnpearson commented 2 years ago

This discussion has now come quite a long way with @mstenta suggesting that we give some thought to formalizing the process of documenting farmOS conventions.

There is a forum topic to think it through with the community: https://farmos.discourse.group/t/documenting-conventions/1263

And a draft Git repository, with an example of what a "soil test" convention might look like: https://github.com/mstenta/farmOS-conventions/blob/wip/docs/soil-test/index.md

We agreed that it would be ideal if these conventions had an ID in FarmOS (in addition to the current quick form type) and that these conventions to document changes to the quick forms and experiment module, which can then be versioned. This would mean we could see which logs were created using which version of the quick forms, and also help with writing update hooks and patches.