MetOffice / MetOffice/ProFSea-tool
Documentation usability review
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 6
- Forks
- 11
- Avg merge
- 13h 34m
- Merged PRs (30d)
- 2
Description
- The documentation for tasks beyond those shown in the example was vague. Additional examples of different use cases utilising more of the options available in the tool (shown in the extensive docstring list) would enable a wider range of input and output setups to be demonstrated and used as a springboard for users.
- The link to detail additional examples of model components appears to be broken. It links to the top-level page of the documentation instead of any details. The full module list would be useful to include to use alongside the worked examples to show what other setups may be possible 'out of the box'.
- Scenarios used are not documented and is assumed knowledge based on the input model dataset. Clearer detailing of where to find this information within ProFSea would be good to document.
In the old ProFSea user guide PDF, there was a table of required inputs which was useful in understanding what needed setting up prior to running the ProFSea tool. Possibly a similar checklist in the documentation would be useful for double-checking a workflow, especially if the inputs require formatting a certain way.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the current documentation, the extensive docstring option list, and the link for additional model components. Compare the old ProFSea user guide PDF for its required-input table. Done means adding varied worked examples, fixing the model-components link, documenting scenarios and where to find them, and providing an input checklist with formatting guidance.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100