A resource for REDCap module development for REDCap admins and developers presented at https://ctsit.github.io/redcap_external_module_development_guide/
Add guidance on the value of a good README as well as a template for a README.md
In the text of the guide, we should tell me about the value of good documentation in making a module accessible to people who don't write code, don't have a place they can test modules, and insufficient time to test them all. We should talk about how REDCap will present their documentation and why a Markdown file is so much more valuable than other forms of documentation.
The template should include the most common elements of READMEs we respect. Here's a starter for the content that should be in it.
Every module README should have these sections:
Overview - The very first section needs to state what the modules does in 1-3 sentences. You might also want to state why the module exists in a second, short paragraph. I.e., explain enough about REDCap to show how this module fills a gap.
Prerequisites - at the very least state the minimum REDCap version number. this is redundant with config.json, but non-developers should not be asked to dig into code to answer such an important question.
Configuration - The redcap module configuration page does not lend itself to explanation. Do that here. You might need both a Global Configuration section and a Project Configuration section. Even if your module has no configuration steps, say it. It will help people understand what the module doesn't do.
Use if people will interact with features the module presents, describe that here. Show it in pictures. Crop the pictures carefully. Annotate the pictures with circles, arrows or text if that makes sense.
Limitations - no module implements every desire. You might have written it to implement one customer's on a limited budget. This is a place to say "This module does not support X, Y or Z". It's kinder than letting people's imagination run wild thinking that it will fix their problem when you never implemented that. This section might evolve as a response to questions and requests for features.
Consider adding the text above as the content in the template to explain what needs to go in each section. In so doing, the template could be self-documenting.
I think these READMEs are good examples to borrow content from or explain the common, but non universal needs in module documentation:
https://github.com/ctsit/save_survey_pdf_to_field discusses tasks that a Project Builder has to perform after activation separately from the data entry experience once the module is properly configured.
https://github.com/ctsit/redcap_css_injector requires CSS skills so it dwells on that issue for an audience that right not understand how to do it. It also provides some examples that are relevant to REDCap to simplify testing and exploration
https://github.com/ctsit/move_data_to_other_event has both Global Configuration section and a Project Configuration sections. It also has a Limitations that describes the risk of data loss when ignoring the limitations.
https://github.com/ctsit/auto_populate_fields implements multiple action tags that have a complex interaction. The README is a valuable tool for describing the subtleties of their behavior.
Add guidance on the value of a good README as well as a template for a README.md
In the text of the guide, we should tell me about the value of good documentation in making a module accessible to people who don't write code, don't have a place they can test modules, and insufficient time to test them all. We should talk about how REDCap will present their documentation and why a Markdown file is so much more valuable than other forms of documentation.
The template should include the most common elements of READMEs we respect. Here's a starter for the content that should be in it.
Every module README should have these sections:
Consider adding the text above as the content in the template to explain what needs to go in each section. In so doing, the template could be self-documenting.
I think these READMEs are good examples to borrow content from or explain the common, but non universal needs in module documentation: