Finalize documentation site index and ontology

[MaxDiz]

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.

[MaxDiz]

@abbyad I took another crack at revising the outline. Can you please review? Looking to remove this as a blocker so we can start migrating current documentation information into the new structure

[abbyad]

Thanks, I'll take another look and confirm here when we're good to move forward.

[smbuthia]

@MaxDiz @abbyad there might be some overlap with what we are working on for capacity building here.

We've put together some app-building modules and within each a list of topics broken down so that each topic contains a manageable amount of content that's easy to grasp in one short sitting. The modules are informed by our learning from past engagements with technical partners as well as conversations with potential technical partners.

I'm happy to chip in and share more insights on this.

[abbyad]

That's very helpful, thanks Sam!

[abbyad]

I am happy with where we are at with the documentation index, and it will continue to be micro-refined as we port over content.

[MaxDiz]

Excellent, thanks @abbyad ! Should we create a set of folders (goog drive or medic/docs or both) to start organizing existing documentation based on the index?

[abbyad]

Yes, I'll do another pass with more of the folders committed (they need files in them)

[MaxDiz]

2 key open items:

• guide section is going to be fairly large and needs review for structure. Current iteration + see current iteration of index
• It's unclear how important it is for Implementing Partners to see App Building detail. The current index structure is cluttered by having this information in-line. What can we do to reduce/eliminate?

Thinking about revising approach to focus on:

1. FAQ - snippets focused on "how do I"
2. Training curriculum
   RapidPro is the current model structure being explored:
   https://rapidpro.github.io/rapidpro/docs/
   https://help.nyaruka.com/en/

[MaxDiz]

To make progress on this issue and #196 , we need we need a better understanding of if/how we are planning to use the CHT Forum in our documentation management process. The Intercom setup that RapidPro uses has significant overlap with the Forum's technical support category. It seems that we've made an Org level decision to use the CHT Forum as our place for community product conversations - accurate?

A couple of alternatives to discuss (related #201):

1. If we want to explore using discourse and a doc site, here is a nice guide from Ubuntu for creating discourse based documentation pages, and their corresponding doc site.

2. If we want to take it step further to create a "real-time knowledge center," Zendesk, can be integrated with discourse. This approach would be both more comprehensive and responsive to users, IMO, but maybe overkill. And, it would likely require some operational adjustments to make it a worthwhile investment. Here's a good example of PagerDuty's use of this approach:

We use it at PagerDuty Community - any topics created in our Support & Feature Requests or Developer categories (or their subs) generate a Zendesk ticket for our Support team to review and respond or forward.

I recall @joshnesbit mentioning having contacts at PagerDuty. If this is an option we want to explore further, it would be worth reaching out to them to better understand their workflows and experiences.

[abbyad]

The index has been evolving a fair bit as I've reworked two primary sources of documentation: the CHT overview, and the reference on developing CHT apps. I think the new structure works quite well, and is quite manageable to receive more content.

Here is what it could look like (using Hugo with the Docsy theme as an example):

The subdivision of the guides section is yet to be fleshed out, and probably easier to figure out now that the app development section is being firmed up.

[MaxDiz]

The most current version of the index can be found in the beta doc site

I have moved all detail from the doc related to how-to-guides into this issue: https://github.com/medic/medic-docs/issues/225