A couple of weeks ago we formed a new working group focused on creating and improving the product documentation that serves to make the Community Health Toolkit more accessible. I’m helming the work, and am joined by @marc@kenn@Nicole_Orlowski@joyanne and @francesca from Medic Mobile, as well as community members @dguo and @riyasingh.
What documentation do you currently feel could be improved or expanded?
What resources should we prioritize creating in the coming weeks/months?
Where have you hit “road blocks” to deploying or configuring the CHT?**
We are striving to make the CHT documentation accessible by seeking out the perspectives of (old and new) partners and end users. We’d love to hear your thoughts in the comments below.
Interested in doing more? Come join the project to help get the CHT into more users hands quickly! Reply here or contact @francesca to learn more.
I’m part of Medic Mobile’s volunteer squad, and I’ve been working with the CHT for almost a month now. My general experience so far with the CHT has been setting up local instances, creating multiple forms for educational content and writing tasks and targets for CHW’s that use those forms. I’ve also done some TextIt integration into the CHT. Documentation I frequently use are
Here are some of the road blocks I’ve had while configuring CHT apps.
Dealing with medic-conf, specifically on my local instance, caused me a lot of trouble in the very beginning. I would frequently use commands in the documentation (for instance, on uploading forms) like medic-conf --local convert-app-forms upload-app-forms
but it would pretty consistently throw me an error. Instead of using the local tag on my instance, I found the command that worked best for me to be NODE_TLS_REJECT_UNAUTHORIZED=0 medic-conf --url=https://medic:password@localhost convert-app-forms upload-app-forms
Being relatively new to XForms, there was a learning curve on how to create them and compile it into the CHT via medic-conf. I figured this out by looking at previous forms and xlxs files in the different CHT configs, as well as reading the documentation. However, I ran into an issue where I had forms that I could access in my CHT instance, but they were not being associated with a contact when I submitted the form and therefore couldn’t count towards targets or tasks (I would get a mark-contacts-dirty error in my console upon form submission). I ended up finding in the documentation that “To make sure forms are properly associated to a contact, make sure at least one of place_id , patient_id , and patient_uuid is stored at the top level of the form.” (Link 2). This issue took me a while to resolve, and maybe having a example xlxs form linked in the docs, then having the docs explain what each group of lines did in the xlxs form (lines 1-20 are metadata that associate the form with a contact, lines 20-100 are lines that produce the contents of the form etc.) might have been useful.
Continuing with forms, dealing with images in the CHT took me much longer than expected. I spent a couple hours dealing with pictures not showing up and only having a spinner until I was pointed to this issue (issue #6321 on cht-core). At that point, I was able to upgrade my instance to 3.8.1, and my problem was fixed. Stating this in the forms documentation probably would have saved some time.
Understanding the hierarchy of a typical health system would have been good to know early on when working on the CHT. I ran into issues while developing apps because I was associating CHW’s on the Health Facility level, however the team informed me that CHW’s typically operate in their own Area, not on the Health Facility level. I’m still in the process of switching my instance around to better reflect this, and having CHW’s on an Area level instead of Health Facility level has made my tasks/targets behave slightly differently. Perhaps having more documentation on how to set up a test dataset and why things are set up the way they are would be helpful (I know there is a way to import test data into a local instance at the bottom of this page (Link 1), but having more instructions as to why things are where they are, as well as including CHW’s in this setup would be useful).
Overall, adding to/improving the forms section of the documentation could be helpful (I didn’t mention the tasks or targets sections in my comments above, but so far haven’t run into too many issues I’ve run into with them).
Hope some of this feedback is useful for the team. Feel free to ask me any questions about this post or my experience in general, happy to help in any way possible.
Hi @David, thanks for the detailed feedback. Your new user perspective on CHT documentation is greatly appreciated!
I’ve created a couple (1, 2) of new issues to fix the challenges noted in your comments two and four, and raised a new PR for comment three.
@stefan can you please do a review of and let @David know if you have any questions?
Dealing with medic-conf, specifically on my local instance, caused me a lot of trouble in the very beginning. I would frequently use commands in the documentation (for instance, on uploading forms) like medic-conf --local convert-app-forms upload-app-forms
but it would pretty consistently throw me an error. Instead of using the local tag on my instance, I found the command that worked best for me to be NODE_TLS_REJECT_UNAUTHORIZED=0 medic-conf --url=https://medic:password@localhost convert-app-forms upload-app-forms
Hi @David, not sure if you’re still actively engaged in your volunteer project, but letting you know that we have just launched a new documentation site. Hope you find it useful!
and let