Looking for a mentor for GSoD2020 project (Improving Documentation for New Developers)

Hi All,

I am a new technical writer and a GSoD 2020 applicant looking for a mentor for the “Improving Documentation for New Developers” project.

There are some discussions around this topic already with @jennifer, @herbert24 and @burke in the following two threads; and I’ve posted a draft project proposal here in the first thread. https://talk.openmrs.org/t/a-possible-new-gsod-2020-project/28947/12

Will you be willing to help me help OpenMRS :slightly_smiling_face:?

4 Likes

@rainbow did you take a look at the Projects for this Year.

@tendomart yes I did. According to the rule of GSoD, the applicants can have their own project idea. :slightly_smiling_face:

1 Like

Thanks @rainbow for initiating this thread,for any interested mentor,you could kindly comment on this thread.

Hey @rainbow

Good to see you interested in helping improve documentation for OpenMRS.

Absolutely. You can propose any idea for OpenMRS GSoD season. However, please note that this year’s list of projects has project named Developing a Suite of Volunteer Guides which covers the scope of your proposed project. In case you want to focus only on developers doc, we can seek suggestions from our documentation team members and mentor. @jennifer @herbert24 @tendomart Would it be possible if we keep the scope of the project to the developer’s doc only?

Well, @rainbow, this sounds good and I really like the idea be blessed for that. What do you think of this?

Am sorry I have been off for sometime because of health issues but I want to believe @jennifer has shared the project scope in detail. Just adding on what @marslan8530 has stated, I believe this project covers all the sections one can volunteer to in the community including their guides which have to be updated and others archived .

Breaking down walls and attracting more devs to OpenMRS

It’s the discussion I have been following closely and I really appreciate each one’s contribution of which the mentioned loopholes (poor welcoming, outdated starters guide etc) can be solved by having this guide in place unlike dwelling on only one section. please feel free to share your views.

1 Like

@marslan8530 @jwnasambu thanks much for the thoughts here,just to make a few things clear,the documentation team has been working closely with @rainbow and we did receive her project proposal.On finding out further,google allows a technical writer to come up with their project as seen here https://developers.google.com/season-of-docs/docs/tech-writer-guide . With that,this puts us at the current step of getting a mentor for @rainbow’s project idea.Thanks

1 Like

Oh, thank you for the brief. I understand now.

1 Like

I think @marslan8530 may be raising a good question for us to consider as we look at our existing guides and think about ways to improve them. At the very least, it raised these two questions for me:

  1. Is there general content, that would be helpful for any type of contributor or volunteer, currently included in the developer’s guide, installation guides, implementer’s guide, etc?

  2. How can this project complement the Developing a Suite of Volunteer Guides project?

I would love to hear what others think.

Thanks to everyone pitching in ideas and thoughts about the proposed project. @marslan8530 @jennifer When I was reading the volunteer guide project descriptions, I have an impression that its main focus is on the administrative side. My proposed project is really on the technical side. What’s more, there are already two existing documents that fit into my project, my goal is to improve and update these two documents.

1 Like

I think we should make the best of this opportunity. While it is understandable that a guide for volunteers would most certainly include Getting started material for developers, technical writers, implementers, and other roles as proposed by a potential candidate but that would require a solid understanding of OpenMRS and would be a formidable task for a technical writer new to our community. However, if we have a proposal strong enough and a candidate who can complete the task within defined limit, I would love to see that guide is completed.

With that being said, a bird in hand is always better than the two in bushes. @rainbow has a clear task list to work on, the mentioned docs do need to be reviewed and by the end of GSoD2020, if we have them scrutinized properly, that would greatly help improve the documentation for developers and in turn, attract more developers for OpenMRS. I would be equally excited looking forward to @rainbow’s proposal as well.

2 Likes

@marslan8530 The proposal was posted in the discussion with Jennifer and Herbert. For the convenience of people in this thread, I am posting it here one more time.

Improving the OpenMRS Technical Documentations for New Developers

Rationale

As the world is suffering the consequences of the COVID-19 pandemic, it is even more evident that an open source medical record system like OpenMRS can be a part of the solution for this kind of crisis. To help the new developers navigate the OpenMRS ecosystem, shorten their onboarding process, and allow more new comers to be able to quickly contribute to the development of OpenMRS, it is necessary to have concise, clear and up-to-date documentations. There are two existing documents for new developers:

However, some of the contents are outdated and the format needs improvement. The goal of this project is to update the content and improve the format of these two documents to make them more user friendly.

Scope

  1. Re-organize the contents and improve the format of these two documents.

For the Getting Started as a Developer document:

  • a. Divide the 17 steps in the instruction into sections, each section contains fewer steps, so that it is easier for the user to follow.
  • b. Re-arrange the order of the steps; some steps can be combined.
  • c. List links to other wiki pages in tables, so that the instructions are more concise and readable.

For the Developer Manual:

  • a. The OpenMRS background information in the first few chapters can be shortened, the users can be directed to the OpenMRS.org page to find out more details.
  • b. The Setting Up chapter should be moved up before the Development Process chapter
  1. Update the contents

For the Getting Started as a Developer document:

  • a. Update environment set up for Linux and Windows (Introduce Docker)
  • b. Update IDE configuration for IntelliJ and Eclipse
  • c. Link to Developer Manual or Developer Guide wherever applicable.
  • d. Make sure all the link-to contents are up-to-date.

For the Developer Manual:

  • a. Introduce the development workflow.
  • b. Introduce how development teams are organized, how team members work together; add links to team meeting, team discussions; help new developers find the teams they might want to join.
  • c. Add Docker in the system setup chapter.
  • d. Add more details about different kinds of modules (reference application module, OWA module and platform module) and how they work together.
  • e. Add simple example codes to show how each kind of module are built and deployed.
  • f. Add simple test examples for each kind of module.

Audience Analysis

The intended audience for the Getting Started as a Developer and the Developer Manual are developers that have little or no knowledge of OpenMRS. There could be two types of developers:

The first type – junior developers with little or no software development experience, for example, GSoC students, who are looking for real world projects to learn about open source software development. For these developers the two documents should present enough details and references so that they can begin to fill in the knowledge gaps, and start to contribute to the OpenMRS projects in a relatively short period of time. The major goals for junior developers are:

  1. Understand the skills needed to participate in OpenMRS (MySQL, Java Spring. React.js, Git etc.) and find the resources to learn these skills.
  2. Join the OpenMRS community, learn the communication tools.
  3. Set up the environment and IDE.
  4. Install OpenMRS SDK.
  5. Understand the development workflow.
  6. Produce simple code to create new modules.
  7. Deploy newly created modules.
  8. Test modules.
  9. Use git to make pull request.

The second type – mid-level developers or senior developers looking to customize OpenMRS to suit their own organization’s needs or to contribute to OpenMRS. For these more experienced developers, the two documents should provide an overview of OpenMRS and serve as a guide to direct them to more in-depth technologies details in the Developer Guide and other resources. The major goals for experienced developers are:

  1. Understand the data model and architecture of OpenMRS
  2. Join the OpenMRS community, learn the communication tools.
  3. Find links to OpenMRS code repositories.
  4. Find more in-depth resources.

Project Plan

  1. Planning phase: (3 weeks)
  • Refine the goals set in the Scope section
  • Identify outdated contents
  • Produce outlines for the two documents
  • Present the outline to the mentor and Subject Matter Experts (SMEs)
  • Update project plan
  1. Content development phase (6 weeks)
  • Learn Docker, produce simple example codes, and simple test code
  • Interview SMEs to ask questions
  • Develop the first draft of the two documents
  1. Content review and publishing (3 weeks)
  • Self edit the contents
  • Send the completed drafts to reviewers (mentor and SMEs) and end users for feedback
  • Revise the draft
  • Publish the two documents in OpenMRS wiki page.
  • Write a project report
3 Likes

Thanks @rainbow for making it more clear ,Am sure it brought all the workaround to be worked on

1 Like

Sorry for taking long to join the discussion.

I joined this great community last year in November, with a little knowledge about development though i hard read plenty of Java programming Books. The fact is that i had made very many personal projects and applications which made me think that am an expert in Java Programming. But when i joined OpenMRS, brothers and sisters, i realized i knew nothing :neutral_face: :neutral_face:.

@herbert24 and some other guys gave me a warm welcoming message with a link pointing on how to get started with OpenMRS. Things were really interesting but i hard to follow my passion of becoming a developer. So without wasting time, i read the developers’ manual. Friends, there are alot of loop-Holes in developers Manual, no-wonder, there are alot of topics on OpenMRS Talk about Failiure to install OpenMRS. I read the developers Manual from cover to cover, more than once, some time spending some days on the some pages, but still i failed, untill @herbert24, @ibacher, @jwnasambu @tendomart @sharif and some other people, helped on talk. The fact is that i was soon dumping the career of programming just because of the OpenMRS installation, and go back to reading Chemistry and Biology. I am not the only person who faced this challenge, i hope, because even @sidvaish97 created a thread, Breaking down walls and attracting more devs to OpenMRS , which is similar to my story.

I know there are alot of arising developers, shaing a story similar to mine, but if this project is accomplished, OpenMRS developers, implements and documentors will increase due to;

  1. Reduction in demotivating Errors while setting up OpenMRS, if not totally got read of. Remember some people out there, with a desire of becoming developrs, join openMRS while they have never seen an Error in there life. They join OpenMRS after watching some learn Java in 5 minutes videos on You Tube.

  2. I believe this project will reduce the traffic on OpenMRS Talk because newcomers will sail through setting-up OpenMRS smoothly, and learning how to contribute easily.

Well @rainbow Thank you for implementing my thought. I strongly Believe that this project is as important as the rest of the projects. However i would also love to be a backup mentor for this project.

2 Likes

@jnsereko thanks joshua and every body sharing thoughts here,i would also like to listen in from joshua about the loop holes in the installation guides.Probably when you get some time,you could drop some message here explaining some of those loop holes and how you think things would have been.It will help to give a broader insight on how we can get this improved.And since we have got a couple of complains in this area,i will get this added to our next documentation call agenda.thanks

3 Likes

@herbert24

Working with Git and React gave me hard time, but the correct MSQL to use for OpenMRS was also another problem. Because i was familiar with some MYSQL before i joined OpenMRS, i knew some of the where, what and hows of solving some little errors in MYSQL. When i was new, i downloaded like three versions of MYSQL before i got the correct one to work with OpenMRS. Actualy i got stark at that point for a week, and @samuel34 came into my rescue. It shouldn’t just end on Stating that “OpenMRS uses MYSQL 5.6.x”(its what i installed, it works for me, maybe it doesn’t for others) but should provide the links to the exact download and installation of the corresponding tool.

The SDK is the simplest, they say, but i prefer Standalone. The command mvn openmrs-sdk:run for running the SDK was my worst problem, yet i hard followed all the steps from the beginning of the page http://devmanual.openmrs.org/en/Technology/getSetUp.html. There is well written information on how to run the SDK but how i wish this information is partitioned to show what is a mandate and what is an option, or even this a link should be provided on this page to direct the reader to more sources of information like wiki… It should even show what is the better alternative (though this differs from one user to another). For example, while creating a server to run the OpenMRS, you can choose either a platform or a distribution, but it would be better to make a choice for the person who is new.

1 Like

@jnsereko, @sharif Thanks for your input. Looks like this is a valid project! I am going to apply for GSoD 2020 using this project. @jnsereko I appreciate your willingness to help as a backup mentor! :slightly_smiling_face:

2 Likes

@jwnasambu I came to this idea from my own experience setting up my own development environment, and I also benefited a lot from this conversation: Breaking down walls and attracting more devs to OpenMRS :slightly_smiling_face:

2 Likes

@herbert24 I am thinking I should come up with a survey to ask people (new developers, GSoC and GSoD participants, and mentors) what they think are the biggest obstacles for new developers. I will first do some research on this from OpenMRS Ask & Talk.

1 Like

that is awesome

1 Like