Platform documentation and hosting infrastructure for first release of MoTeCH

[Vivek Singh]

Types of documentation available to the users of MoTeCH

- User documentation (Architecture, Features/Modules, Configuring modules, Deployment, Maven Repository)

- Developer documentation (Dependent software setup, Build, CI)

- Javadoc

Any preferences/recommendation for where we should host these?

Also, what documentation we should target for the first release?

--
Vivek Singh | +91 98452 32929 | http://sites.google.com/site/petmongrels | petmongrels@twitter

[Bruce MacLeod]

A graduate student, Russell Gillen, and I have started work on
developing documentation for implementers. Our first attempt for the
message campaign module is at :

http://motechdocumentation.wikispaces.com/

From the comments of Rob and Tim, it seems that this a reasonable
approximation of what is needed for module documentation for
implementers. We are working on the outbox module now.

I have the same question about where to put this documentation.

Also, it would be helpful if Russell had access/introduction to a
developer (s) who can answer questions when we have difficulties
understanding the code.

[Rob LaRubbio]

I think it makes sense to choose a tool for the doc and then host it on
motechproject.org. I'm not sure what that tool should be. :)

I think the first round of documentation we want to tackle would include
a lot of what you have listed under Developer documentation. Then I
think we'd want to move into the user documentation. Do we have a list
of which modules/platform features are done?

-Rob

[Vivek Singh]

Regarding hosting, can we use github? As a user I find it convenient that documentation and source code are in same place. I also like them for the fact that they understand what it means to host an open source project.

[Bruce MacLeod]

Any progress on the OSGi work ?

In looking the current software, it seems that only a few modules are
actually "OSGi" bundles :

motech-appointments
motech-outbox
motech-pillreminder-0.1
motech-platform-decisiontree

Also, these bundles do not have much in the way of clearly defined
external services.

If we move forward with OSGi, I thought it might be worthwhile to
consider the following tool :

http://www.ops4j.org/projects/pax/construct/index.html

We use it to build OSGi infrastructure and resolve references.

Bruce

[Rob LaRubbio]

Additionally it looks like the OSGI initialization was removed in this checkin (see line #55):

https://github.com/motech/MOTECH/commit/81e865cb550fb135670020434ef22245cccc333e#diff-20

Adding the init and destroy method arguments back in I can once again load the osgi modules, but it looks like they have become stale and no longer load. 

-Rob

[Vivek Singh]

I guess the issues has been:

- lack of understanding on our part as to what is really required to have OSGi working, and why should we even have OSGi.

- no tests fail when such code is removed.

- no implementation is using the OSGi mode.

We would be picking up an implementation (most likely Ghana-MTN) to use the platform as a container and also using OSGi. I am hoping after this we should also have ability to use platform as library but with OSGi in embedded fashion.

We are hoping to kick this off soon, but meanwhile if you want to use any module in OSGi fashion please go ahead and add what you need, along with a test.