Refactor README

[dbuscombe-usgs]

wishlist

• [x] major headings a) DATA PREP, b) TRAINING, c) EVALUATION with minor headings with every aspect in chronological order
• [x] eventually move some content to a wiki, website, or external doc

[dbuscombe-usgs]

some good advice here for the readme only https://github.com/banesullivan/README

[dbuscombe-usgs]

I

• [x] rewrote the readme
• [x] added pages to wiki for home, config file, directory structure, and model training

needs additional wiki pages for (at least)

• [ ] model evaluation
• [ ] single model deployment
• [ ] ensemble model deployment
• [ ] troubleshooting

what badges can we add to the top of the readme?

add other minimum requirements like Python versions or operating systems - what have been tested so far?

[ebgoldstein]

added some badges, and migrated the model description section to a wiki page

[dbuscombe-usgs]

from @2320sharon

First Impressions

1. I like the new labels for tensorflow, keras, and python because they make it easy to understand the general framework and requirements for Zoo to run.
2. Organization with emoji’s is fantastic! I actually saw this in an article on how to write great ReadMe pages.Highlights Section
3. The highlights section makes it easy to get the gist of the project. One question: Can Zoo use only Unets now or are other models included as well. It might be a good idea to list the three types of models it can use.

Overview Section

• I’m not sure what “model ready” entails is it possible to elaborate on this?
• The bullet points are helpful for dividing out what Zoo is capable of.
• Typo: “which is the authors' motivation” -> “which are the authors’”

Usage Section

• The directory structure link is broken.

• In the wiki: I also would bold the point that the directory containing the sample data cannot be in Zoo Additionally when I first ran Zoo I was confused by the fact that within the “fromDoodler” folder within the images and labels folders respectively were additional folders called images and labels inside.

• For line “5. Train_model.py” can we insert a warning emoji and state that if they don’t have a tensorflow GPU they can’t run this program? Nice to have : Can I add a link to the definition of an ensemble model or is this too much?

https://www.sciencedirect.com/topics/computer-science/ensemble-modeling

• “Zoo HQ also advocates the use of ensemble models where possible, which requires training multiple models each with a config file, and model weights file

• Does each model need its own independent config and model weights file or can they be reused?

Directory Structure and Tests

• “We strongly recomment “ - typo recommend
• I also would bold the point that the directory containing the sample data cannot be in Zoo Additionally when I first ran Zoo I was confused by the fact that within the “fromDoodler” folder within the images and labels folders respectively were additional folders called images and labels inside.

[dbuscombe-usgs]

Incorporated suggestions from the above review

decided against (at least for now) a graphic showing the overall process... closing