medic / medic-docs Goto Github PK

Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you'll need to license it so that others are free to use, change, and distribute the software.

For more information see: https://help.github.com/en/articles/licensing-a-repository

We support creating Enketo forms with embedded images, audio, and video but we don't have any documentation on how to configure it.

Update this page with a section on multimedia, and include:

• How to configure it.
• What encodings are supported for each media type. We use HTML5 rendering so these will be whatever the browser supports.
• What encodings are recommended, eg: better compression rates, better hardware acceleration for video decoding, etc.
• Recommendations for file sizes, particularly for video.
• Recommendations for image and video dimensions (eg: there's no point having lots of pixels and then scaling it down to fit on the phone screen).
• And anything else you can think of.

To get started have a look at the multimedia demo form.

All content from medic-docs that has been moved to the new doc site should be removed from medic-docs to avoid confusion and stale content.

Once all content has been removed we can see discuss what to do with the remaining content (eg move it, or archive repo)

As a product team member, I want clearer definitions of client-side telemetry data access and output, so that I can effectively measure how our product performs and how users are engaging with features.

Requesting documentation on:

• Which data sets are available for queries and when they became available (ie earliest possible query date)
• How to perform client-side telemetry SQL queries
• Instance telemetry clarification on data fields, measurement units, and frequency of data availability
• Aggregate telemetry clarification on data fields, measurement units, and frequency of data availability

This is a follow-up to medic/medic-projects#6882

Documentation squad has picked a top-three tools for https://docs.communityhealthtoolkit.org/. Kenn is assigned to investigate Hugo.

@TamorHaabmets reports:

I tried it out and i had some permission problems when running grunt. Error message was:
tar EPERM: operation not permitted, futime
These two commands helped me out (insert them in your linux home directory).
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata,uid=1000,gid=1000,umask=22,fmask=111
More info:
https://stackoverflow.com/questions/56457844/tar-eperm-operation-not-permitted-futime

Investigate and update the instructions as needed.

cc @SCdF

The CHT has an initial draft of the CHT documentation site (and GH repo) up and running. It uses Jekyll, primarily because of the built-in integration with Github Pages. The template is cumbersome, especially for the index, and not well suited to our needs. We are experiencing some challenges with layout, missing key functionality, etc, and have decided to explore alternative tooling options.

Documentation site requirements and priorities are below. Please add to this ticket

Easily navigable

• table of contents/index (must have)
• hierarchy- headings and subheadings. Link to any heading (must have)
• Same page appear multiple times in table of contents (very nice to have)
• Search for both google and internal doc site (very nice to have)
• Tagging for related or prerequisite docs (must have)
• Some kind of app versioning support
  *Option 1 - Annotation to indicate features added/removed by version (must have)
  *Option 2 - Some sort of tooling support for changes between versions (not required at this time)

Content types support

• Markdown (must have)
• Text / Functional description (must have)
• Multimedia- screenshots, gifs, video demos, step-by-step tutorials (must have)
• Code blocks (must have)
• Tables (must have)
• Tutorial modules- bite-sized education/learning opportunities pulling from multiple pieces of information across the platform (nice to have)

Embedded assistance - integrate with CHT technical support forum - disqus platform (very nice to have)

Information portability to complimentary platforms, and ownership/control (very nice to have)

Support for language translation (must have; open to 3rd party services)

Usable offline (nice to have)

Easy to contribute regardless of technical capabilities should be friendly for all team members to contribute. Github requires some training, but not insurmountable. Are there other good options to consider? (must have)

Single sign-on (OAuth) (very nice to have)

The CHT documentation site needs to be easily navigable so users can quickly find the information they need. As an initial step to answering this need, we created an overview of features and functionality of the CHT.

As a next step, we are looking to integrate this information into the documentation site, and build it out further to incorporate full feature tours, app building guidelines, key workflows, and administrator details. Additionally, we would like to define relation between the concepts wherever possible to make it easily navigable by users.

We have create this draft outline to capture current thoughts. It needs to be finalized to move forward with buildout of the documentation site.

In the Creating a blank project documentation, it gives a few commands to run, but the third command does not work as written (at least for me). I think it's fine to assume a specific scenario ( local, for example) and I think we should update the documentation to be more clear.

mkdir cht-app-tutorials
cd cht-app-tutorials
medic-conf initialise-project-layout

When I did medic-conf initialise-project-layout, it gave me an error.

If I do medic-conf --local initialise-project-layout it worked fine (with a few warnings).

https://github.com/medic/medic-docs/blob/master/configuration/replicate.md => 404
The link is from https://github.com/medic/medic-docs .. entry Replicating with Futon
Seems to have moved to https://github.com/medic/medic-docs/blob/master/configuration/legacy/replicate.md

As part of the review of existing documentation (#195) we will work out which documentation resources should be migrated to the improved documentation site. If a resource is in a format other than markdown, it will need to be converted. This issue is to capture all resources that need to be converted to markdown in preparation for documentation site launch.

The current approach illustrated in https://github.com/medic/medic-docs/blob/master/configuration/forms.md is causing an overallocation of memory (and crashing on low RAM phone).

Use the identified workaround in medic/cht-core#6136 and update the example(s) in https://github.com/medic/medic-docs/blob/master/configuration/forms.md

In this doc: https://github.com/medic/medic-docs/blob/master/md/install/smssync.md, the URL examples
have "http" instead of "https". This is confusing the PMs or anyone following the guide to setup the SMSsync.

Based on the CHT documentation site functional requirements (#193), we want to do a review of available out-of-the-box solutions that most closely match user needs. This ticket is to document potential solutions and key considerations for decision making on documentation tooling options.

click around a bit through the docs and eventually bootstrap dropdown fails proper initialization. you get a 'document not found' error and console msg:

Uncaught TypeError: Cannot read property 'fn' of undefined :5984/kujua-docs/_design/kujua-docs/_rewrite/jam/bootstrap/js/bootstrap-dropdown.js:78

We have compiled a comprehensive list of existing CHT documentation. It needs to be reviewed and integrated into the revised site index (#194). During the review process we should:

• de-duplicate existing resource information
• work out which existing documentation resources can be ported directly to the documentation site
• identify required improvements to existing documentation resources before they can be added to the documentation site

Add configuration documents used mostly by tech-leads, most of which has been lying around in Google Drive.

Topics

1. AWS Instance Creation

• Instance creation request using GitHub
• Instance creation process

2. Medic Gateway

• List of phones that work well with Medic Gateway
• Configuring Medic Gateway
• Troubleshooting Medic Gateway

3. Medic Collect

• XLSForms
• Pyxforms
• Building Medic collect apk
• Troubleshooting

4. SIM Apps

• Creating sim app forms
• Creating converting sim app forms to trb files
• Installing trb files to sim cards
• Troubleshooting

5. Medic Web App Configuration

• App settings configuration
• Uploading new/edited forms to the webapp
• Uploading new users to web app
• Troubleshooting

6. Klipfolio Analytics

• Klipfolio functions
• Klipfolio creating datasources
• Postgresql - couch2pg
• Troubleshooting

7. Medic XLS and Nitty Gritty

• Medic XLS
• Medic Nitty Gritty

8. Scripts

• User creation
• Contact deletion

Based on the outcome of #196, we may want to implement new documentation tooling. Implementation of the new documentation tooling should reference #194 , #197 , and #202. This ticket is to capture related implementation detail once a pathway is determined.

Gaining insights into how users engage with the CHT documentation site will help us to determine user uptake, what self-help information users reference most frequently, and which information sets are largely disregarded. Since the documentation site is an online-first resource, implementing telemetry should be straight forward, using an off-the-shelf tool like google analytics. Relevant telemetry points include:

• unique users
• returning visitors
• session length
• page sessions (should be segmented by index sections #194)
• keyword searches
• bounce rate
• click through rate to the support forum (contingent on #201) and other resources if added
• geographic locations (may be relevant for #192)

Set the version number from step 1 in medic-webapp kanso.json, package.json, and npm-shrinkwrap.json. If releasing a new major or minor, also set the versions in master to be the next version (e.g. .<minor+1>.0), so that the alpha builds will have the right version.

from https://github.com/medic/medic-docs/blob/master/development/releasing.md

Once currently available documentation is integrated into the site index (#195), we should do a complete review to identify gaps in key information. This issue is to capture documentation resources that are missing altogether at the time of improved site launch. Missing resources should be noted within the index structure or added to this issue using the format: [index section] - [subsection] - [description of missing information].

We should include a description of the known field in our users documentation.

https://github.com/medic/medic-docs/blob/master/development/db-schema.md#users

As a partner, I need clear documentation on how to interact with CHT data from outside applications so I can extend the platform by integrating with complimentary tools.

Ideas for documentation that would be useful:

• API endpoints
• convention(s) followed (ie REST)
• rate limiting on data requests
• authentication requirements
• data formats and translatable values (ie language, numerical, date)
• testing protocol
• Identifier schemes for mapping metadata objects
• user profile requirements for adding/deleting objects
• validating payloads and data element constraints

cc: @ranjuts @kennsippell

Probably include a script tag at the top that checks if there is a trailing slash on the root and if not sets the location.

Including

• an overview of nools and the TaskGenerator
• inputs to the rules
• expected outputs from the rules, including how actions work
• utility functions available on the Utils class

It would be great if you could add a CONTRIBUTING.md file to this repo that outlines the guidelines to make contributions to the documentation repository.

Brief overview of the initiative
document the standard aspects of our current site and provide tips for consideration when choosing a design

Link to the google drive folder where info for the initiative is being managed
https://docs.google.com/document/d/1KXW5q8NWTeD_iF35aWOXqw4XYY7dPWNLtBDFu1MsHiE/edit#

We could use some more documentation on managing forms for adding and editing contact forms, including forms/contact/place-types.json and the generic forms/contact/PLACE_TYPE-create.xlsx and PLACE_TYPE-edit.xlsx.