Steps to follow to do a documentation review

1

Hi all, We’ve slaved away for weeks on openmrs New Developer and user guide documents. We’ve researched and reached out to the community concerning their views. We’ve worked hard to understand the audience, their needs and how they will use our work. Now it’s time for the document review and test phase.

Try these five steps:

1. Develop thick skin. If someone finds your message is unclear then you need to improve it.

2. State your purpose clearly. Since we know what the document is intending to do, judge the feedback you receive in the light of the purpose.

3. Identify real users. The target audience is the best people to tell you how well your document will work. For this case we are targeting the User and New developer persona.

4. Prepare document review questions.

These are questions to help reviewers engage with the guides:

  • Does this document contain information or ideas that are important to the persona?
  • Can you easily find the information needed?
  • Once you find the information, can you understand it?
  • Does it tell you too much or does it tell you too little?
  • Is the information correct or could it be misleading?
  • Do you know what to do now that you have read this?

5. Make feedback easy by leaving a comment on the document or just insert the correct content.
Feel free to add any step you feel is left out. Thanks for your support we meet 4pm EAT and 1pm UTC in cyber space.

The conference is open to everyone with our contribution focusing on New developer’s guide and user guide.

Thanks.

cc @c.antwi, @ruhanga, @jennifer, @dkayiwa, @irenyak1,@burke, @herbert24 , @dkayiwa, @lana, @monasaleh, @odorajonathan, @georgejr, @collinewait, @gcliff, @ball, @terry, @janflowers, @carina and @jwnasambu

3 Likes
2

thanks julie for this @jwnasambu

3

@jwnasambu this is awesome! Is there a place or document(s) you would like us to specifically look at for review?

4

Yes . We are concentrating on openmrs Developer’s guide and User guides for now.

5

Just a reminder friends, today we are meeting at 11am EAT to share our findings. The conference is open to everyone. To join follow this link.

6

Apologies for not be able to attend the meeting. for some reason it did not appear in my calendar.

Let me know if you would like to convene tomorrow morning at 10am EAT?

7

Its ok let me mobilize members we do it before the 4pm call so that we have something tangible to present.

1 Like
8

Can you link those here?

9

Sorry @janflowers for not showing the links: This are the links

  1. https://wiki.openmrs.org/display/docs/Developer+Guide

  2. https://wiki.openmrs.org/display/docs/User+Guide
    See you in tommorrow’s call.

10

Hello friends, today we have a meeting at 4pm EAT, but it was requested we meet at 10am EAT to go through what we have on the table in preparation for 4pm call.

11

Hello friends hope all well. Observation made is the following links should be moved from User Guide and where could they fit?

Kindly share your views.

1 Like
12

@dkayiwa am reviewing this link https://wiki.openmrs.org/display/docs/Step+2+-+Install+Java of user guide. I just wish to inquire the minimum version of Java version to be used because last year Java 7 wasn’t that effective.

1 Like
13

Platform 2.x and above require Java 8

Older versions work fine with Java 6 and 7

14

Thanks for the clarification.

15

@dkayiwa am reviewing page. Does this close

With OpenMRS 1.8 it is necessary to increase the Tomcat Permgen memory before deploying OpenMRS. More information: Troubleshooting Memory Errors - Documentation - OpenMRS Wiki

also apply to openmrs versions higher than 1.8? With MySQL version should I change to version 5.6? because that is version I always see you recommend people to use.

16

Kindly use this link to indicate all the proposed changes to be made on a given page for easy review.

17

@jwnasambu for a number of pages, i have seen some legacyui documentation being overwritten with information for the reference application. Because the legacyui is still in wide use, can we instead create separate documentation pages for the equivalent reference application pages.

1 Like
18

Thanks for the comment and review let me see the way forward.

19

@cpear98 , @ryansle and @tristan10 Thanks for the work done. I kindly request we fix this issue.

20

Thanks for the feedback. I am currently in the process of making a new landing page and subpages for the reference application documentation and reverting the changes to the legacy ui docs.

1 Like