GabrielThrasher
commented
5 months ago Writing/style is professional and overall really good.
Clarity is really good and will leave no ambiguity or questions for the reader: (I will write out what I thought each paragraph did well at explaining to (1) make it clear what I though each paragraph talked about so whoever reads my comment can correct me in any areas I might of misunderstood and (2) make sure that all the big points that the documentation writer wanted to get across did come across to a first-time reader.)
- The importance of annotations (and what type of data is included in annotations) being explained in the first paragraph is extremely helpful to put into context why we need annotations, especially for readers who may not have much background dealing with data annotations.
- The second paragraph is great at giving a structural overview of the data annotations that is used for the R program associated with it. id variable is clarified well.
- In the third paragraph, the purpose/goal of of_variable is explained well. Again, the goal/importance of data annotations is perfectly restated and expanded upon.
- In the next two paragraphs, is_type and with_entry are explained well.
- The example table does an excellent job at summarizing what has been said so far in the document. It helps solidify what has been said to readers who learn by example or through visuals.
- "Read the documentation" and "Checking the annotations" paragraphs do a good job at explaining best practices when creating/verifying a data annotation table.
Overall, I feel like just given this documentation, I could create a proper data annotation table for the associated R program.
ktoddbrown
Review the annotations page for clarity and writing.
https://github.com/ktoddbrown/SoilDRaH/wiki/Annotations