VOTE on a Big Change for our Wiki / Documentation

Development
,
1

The Problem: So - we have a longstanding issue: There are a bunch of key topics/concepts that are helpful to know about OpenMRS, and can apply to any (sometimes all) of these 3 guides: (1) The Developer Guide, (2) Implementer Guide, (3) User & Admin Guide, etc.

Examples of some of the pages that we need to re-use in multiple guides:

  • :toolbox: Data Model & Architecture Overview
  • :pencil: Forms
  • :globe_with_meridians: Translation
  • :books: Concept / Dictionary Management
  • :bar_chart: Reporting

The good news: The newest version of Confluence (which we now use) allows “Smart-Links”, which enable you to have a page in multiple places, but it’s not duplicated and any edits update the “Mother” version (feels kinda like an iFrame). So e.g. we can have the “Forms” guide in multiple places, without worrying about duplication, or it getting missed. Example here: You can see the Concept Guide is being pulled from elsewhere, but is still in a sensible spot in the Admin Guide.

Image showing how to add a Smart Linked page somewhere:

image
image710×532 16.2 KB

Time to Vote!

Proposal: In the Documentation Revival Squad we’ve been talking about this issue. We propose having a single spot in the docs for “Key Topics” like this, which we can then re-use (via Smart Links) in persona-specific guides. Here’s how such a page would look:

Demo of OpenMRS Key Topics in Wiki

I’ve experimented with this in the Wiki to show what it can look like - :backhand_index_pointing_right: have a look here :backhand_index_pointing_left: (Don’t worry, it’s super simple to revert this if people don’t like it.)

Poll #1: What do you think of this idea?

  • :+1: Good idea
  • :thinking: I have some concerns (I’ll share below)
  • :exploding_head: I have BIG concerns (I’ll share below)
0 voters

Poll #2: If you are ok with this idea, what should we call this section of the wiki?

  • OpenMRS System: Key Topics
  • OpenMRS System: Building Blocks
  • OpenMRS System: Fundamentals
  • OpenMRS System: Essentials
  • OpenMRS System Overview
0 voters

Looking forward to hearing what people think!

2 Likes
2

Thank you so much to everyone who has voted so far! I’ve enjoyed seeing the results come in.

@chintu I see you selected you have big concerns - can you share what your concerns are?

1 Like
3

Sorry, @grace actually , I have voted for a good idea :smiley:

4

So, I’m on-board with the having reusable sections like this. I’m a little less sure about the classification of these topics into a single category because these topics seem to have somewhat different audiences. E.g., the documentation on “Forms“ would likely have some small developer notes, but the bulk of it is aimed at implementers / who ever is responsible for building the forms; “Translation“ seems like we’d have again, some notes for developers, but then also a fair bit of documentation on Transifex (which is more aimed at community translators), but it also has an important (and large) overlap with the concept dictionary, which is (in this role) largely a implementation concern, etc.

1 Like