GSoD 2020 - Improving Technical Documentation for New Developers

Tags: #<Tag:0x00007f0a2a80d1e0>

Can any of the content under For Module Developers, especially under Creating Modules, help with this?

1 Like

Hi @jennifer, good suggestion. I haven’t gone through those wiki pages in detail. I will spend some time to investigate. Thx.

Hi @herbert24,

Is OpenMRS SDK bundled with jetty? The reason I am asking is in this installation guide, it says that jetty is included in the OpenMRS platform. Since we want the new developer to use OpenMRS SDK instead, do they need to install jetty separately?

I have some confusion about the terminology when we say OpenMRS core, is it the same as OpenMRS platform?

@herbert24, @ayesh I’ve seen IRC being mentioned in many places in wiki pages. Is it still being used often compared to Talk, Ask, and Slack? Should new developers be introduced to it?

Hi @rainbow!

Here are a couple of resources that might give you insight into how we’re using IRC and Slack:

https://wiki.openmrs.org/display/RES/Communication+Channels

Also, @burke has created a bridge from IRC to our #general Slack channel so that conversations in IRC are also visible in Slack.

Thanks @jennifer. Burke just gave me a detailed answer about IRC. As Slack has some restrictions, we will keep using IRC in the community.

@jennifer, is there a reason why the Developer Manual is created with GitBook not with wiki? I am wondering how this document is used and distributed (is it printed out)? There is a lot of overlapping information with what’s in the wiki. Is it necessary to keep those overlapping info or is it sufficient to just link to the existing wiki pages?

I am looking to improve the organization of the manual, working on a new outline.

The developer manual, like the implementer’s guide, started out as FOSS manuals with the goal of being self-standing references for devs & implementers that could be (and were at one point) printed out as books. Since the FOSS manuals weren’t easy for people to edit, we translated them into Git Books as part of a Google Code-In a few years ago.

Some people find the wiki difficult to navigate and it doesn’t lend itself as easily to becoming a book. But there is certainly overlap and it would be nice to reduce or eliminate maintaining the information in multiple places.

The wiki tends to be a collection of self-standing pages that are easier to edit; whereas, the books try to tell a story, so they aren’t exactly the same.

2 Likes

Hi @burke, thanks for the help. So you think the Developer Manual should remain a book format that can stand alone?

Hi All, This is a revised version of Getting Started as a Developer. It is both a draft and an outline. Please provide your critique and feedback. Thank you!

1 Like

Thanks @rainbow i am reviewing this and any other person is free to review

2 Likes

nice work @rainbow

1 Like

hi every one,kindly help us get some time and have a look at works done by @rainbow here https://docs.google.com/document/d/1lG_Jd7oi-6g4LEwbEF5jblq_qsQrK8FkYsau10BM3hY/edit Your feed back will greatly help in making the document better,thanks cc @dev1,@dev2,@dev3,@dev4,@dev5

1 Like

@rainbow,you can also open up the document so as comments can be added

1 Like

Thanks for the work done​:clap::clap::clap:

2 Likes

Hello everyone and @herbert24, the draft/outline is open for comments. Please let me know if I left anything important out.

1 Like

@herbert24, @jennifer, @burke, @madhens, @ayesh
I need your take on this:

The project also includes improving Developer Manual.

There are three options regarding the content:

  1. Keep the overall structure ( maybe improve upon it), and update the content.
  2. Separate out the background info (OpenMRS history, the software, where we are as an organization, how the community work together etc), and let it become a part of the general guide for volunteers (not just developers); the technical part (data model, architecture, set up etc) can become a separate document just for volunteer developers.
  3. Eliminate the technical part altogether, take parts (architecture and data model) that are relevant and put in Getting Started as a Developer instead.

And there are two options for the format:

  1. Let the document stay the Git-book format.
  2. Let the document become a part of the wiki.

Hi @rainbow!

My preference would be to separate out the background info and make that part of a more general guide for all contributors coming to OpenMRS.

And in terms of format, I think we need to go with the format that is easiest for our community to maintain over time. There are definitely things we can do with our Wiki to avoid entropy - and I have a feeling that it’s harder with Git-book (as nice as the Git-book format is!).

2 Likes

Hi @jennifer, Thank you! Those are my preference also! :slightly_smiling_face:

@rainbow Hi rainbow,i added a couple of comments on your google doc.kindly check them out when you happen to get some time!

1 Like