GSoD 2020 - Improving Technical Documentation for New Developers

[jennifer (Jennifer Antilla)]

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

[rainbow]

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

[rainbow]

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?

[rainbow]

@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?

[jennifer (Jennifer Antilla)]

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

Trialing Slack for the OpenMRS Community

We’ve had several conversations over the years about trying Slack.[1, 2, 3] We’ve also run into some downsides of Telegram.[1] When the Micro Frontends work started up this year, it began fairly organically amongst teams who were already using Slack for their work. In order to try to pull those conversations into a community space without being disruptive to those developers, we dusted off our Slack workspace. Yes, Slack has downsides for an open source community. But it’s also one of the most …

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

[rainbow]

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

[rainbow]

@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.

[burke (Burke Mamlin)]

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.

[rainbow]

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

[rainbow]

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!

[herbert24 (Herbert Yiga)]

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

[ayesh (Ayeshmantha Perera)]

nice work @rainbow

[herbert24 (Herbert Yiga)]

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

[herbert24 (Herbert Yiga)]

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

[gracebish (grace nakiguli)]

Thanks for the work done​:clap:

[rainbow]

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

[rainbow]

@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.

[jennifer (Jennifer Antilla)]

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!).

[rainbow]

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

[herbert24 (Herbert Yiga)]

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