Request for Review


(Adam) #1

We have recently cleaned up and reorganized the Collect and Aggregate sections of the docs.

If you haven't checked out the docs in a while, now would be a great time to do so!

It would be helpful to get additional eyes on this content. Reviews for style are appreciated, but technical review is especially needed. That is --- if you are in a position to review for technical accuracy and completeness, your help would be appreciated.

Of particular concern to me are these two documents:

Sysadmin stuff is a little outside my expertise, so additional support from you all to ensure this is accurate and useful would be really great. If you have the time and wherewithal, following the guides to complete a from-scratch install of Aggregate, and reporting back if you have any problems or hangups, would be extremely helpful.

(If you do this, you can feel free to submit a PR on the docs to update/correct them. But also --- if you don't have the bandwidth/desire for doc writing, that's okay too. You can file an issue or just comment here with your feedback.)


(Yaw Anokwa) #2

@iamnarendrasingh @Ronald_Munjoma @robbyoconnor If either of you has a moment, this would be a great contribution!


(Caroline) #3

Thanks for the docs work! One problem we ran into recently installing, which I know was reflected in earlier versions of the Tomcat documentation, but I could not spot in these (possibly just missed it), was the size of our tables--they were too big for MySQL! If you could make sure there is a warning/tip about tables size and to use PostgreSQL (not MySQL) if you have larger tables, that was key info for us in the old directions.


(Adam) #4

What do you mean by larger tables? Do you mean more records? Or more columns (data points per submission)? Or both? Or something else?


(Caroline) #5

The problem with MySQL was definitely columns (even with blank forms with no data), not records. There's some discussion here:

http://opendatakit-dev.cs.washington.edu/1_0_tools/aggregate/tomcat_install

in the "Despite MySQL's overwhelming prevalence," paragraph that would be helpful to summarize/retain in a warning.


(Adam) #6

Thanks.

Issue added: https://github.com/opendatakit/docs/issues/440


(Jason Ives) #7

This is great. I did a quick review of the collect section and have a couple suggestions.

ODK Collect:
http://docs.opendatakit.org/collect-install/
On the first note, you might want to mention that an old fashioned side load and manual install will work as well, you don't have to use ADB or a 3rd party app to do it, just a USB connection to a PC with the file is sufficient.

http://docs.opendatakit.org/collect-forms/#loading-forms-directly
Editing Saved forms & Uploading Finalized Forms seems like a strange fit for this page. I would probably separate coverage of blank survey forms vs completed (or not completed for that matter) survey instances. Also having instructions for editing a form come before instructions for filling one out feels backwards.

Overall it looks good.

Jason