Hey all,

We now have some good momentum on documentation (both at platform and
product-level). Before we once again have too much documentation living in
too many different places - Confluence Wiki, GitHub Wiki, GitHub pages, I
would like us to try and standardize in one location.

For at least our end user product-related documentation (and perhaps some
of our platform documentation  - not API level but what Keith outlines
below), I am proposing we use Confluence as it provides a solid interface
for both technical and non-technical users, good navigation, integrates
well into our existing community infrastructure and provides the
flexibility in output formats we need for packaging it up and sharing
(HTML/PDF).

I know that being generated in HTML format is a concern but it seems the
Export to HTML feature would work and with each release, we could generate
an HTML export of that current snapshot of documentation:
https://confluence.atlassian.com/display/DOC/Exporting+Confluence+Pages+and+Spaces+to+HTML

Confluence provides a nice documentation theme to guide setting up a
documentation space:
https://confluence.atlassian.com/display/DOC/Creating+your+Technical+Documentation+Space

Some downsides - our Confluence site isn't as search-engine friendly as
some of our other web properties and it might not have the exportability of
a tool like FLOSS Manuals (but FLOSS Manuals caused us a lot of delays in
the past). Localization is also a concern.

Any thoughts on this proposal or other suggested tools?

Background
=========

Here is a link to some reflection on our documentation needs:
https://mifosforge.jira.com/wiki/display/MIFOSX/Streamline+Mifos+X+User+Documentation

and below is Keith's recommendation and some additional background:

5. Platform documentation

Since the beginning of mifosx platform development we have included API
docs that detail what the platform can do. The intended audience for these
are application developers.

All documentation MUST be bundled with the version-ed release artifacts. We
don't want a split between the code and documentation parts of a release.

In this area we are going to look into producing even better documentation
for the application developer and streamline/automate the area where
possible.

At a platform level we probably also want to provide documentation on the
following areas:
   - Installation/Deployment Guides (local, cloud, multi-tenant, mutli-node
(load balanced, multi-aws-region etc)
    - Database documentation: Clear explanation of schema and how it
relates to 'api' functionality in general.
    - Platform functionality documentation: Document the main concepts of
the platform both technical and domain related (micro finance)

Ideally we would be able to tie in the 'API' documentation with the related
documentation that explains in natural language the concept of the system
(whether technical or domain related) and along with that the database
schema documentation that relates to the API/concept area. The idea being
to make it easier for the application to grasp/understand in whatever
detail they wish the particular area

6. Product related documentation

Each product created on the platform will end up creating their own
documentation as this is typically targeted at the end user with lots of
screen shots and step by step instruction on how to do things. For the
community-app any documentation related to it should be released with it.

In common with the platform documentation it most likely needs to be in
easy to view format (html, pdf or both) and most organisations out there
would probably like to be able to brand the documentation as their own too.

-- 
*Ed Cable*
Mifos Community Manager
Director of Community Programs, The Community for Open Source Microfinance
[email protected] | Skype: edcable | Mobile: 484.477.8649

*Collectively Creating a World of 3 Billion Maries |
*http://openmf.org <http://facebook.com/mifos>
  <http://www.twitter.com/mifos>
------------------------------------------------------------------------------
Sponsored by Intel(R) XDK 
Develop, test and display web and hybrid apps with a single code base.
Download it for free now!
http://pubads.g.doubleclick.net/gampad/clk?id=111408631&iu=/4140/ostg.clktrk
_______________________________________________
Mifos-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/mifos-users

Reply via email to