[kepler-dev] [Bug 5327] New: Need to fix documentation system

[bugzilla-daemon at ecoinformatics.org]

http://bugzilla.ecoinformatics.org/show_bug.cgi?id=5327

           Summary: Need to fix documentation system
           Product: Kepler
           Version: 2.1.0
          Platform: Other
        OS/Version: All
            Status: NEW
          Severity: major
          Priority: P2
         Component: documentation
        AssignedTo: altintas at sdsc.edu
        ReportedBy: david.v.welker at gmail.com
         QAContact: kepler-dev at kepler-project.org
   Estimated Hours: 0.0


Our current documentation system creates a lot of unnecessary work and has
excessive overhead to produce updated documentation for even minor changes. As
a result, documentation tends not to be updated incrementally as would be
ideal. Also, at release time, dealing with the production of documentation
consumes much more time than it should.

Basically, the approach we have now is that our documentation is separated into
Word documents, one Word document per chapter. Already, this limits the ability
of people to contribute to the documentation to those who have Microsoft Word
or perhaps OpenOffice. Requiring users to have Microsoft Word already goes
significantly against the spirit of an open source project in my view. While
OpenOffice, in contrast, is open source, I am not sure if it is fully
compatible or not. It probably is if all you are editing is text, but may have
more difficulty with other sorts of document structures. Further, since the
documents tend to be large, it often takes quite a bit of time to load, even
though this is partially ameliorated by only storing a single chapter in a Word
document. Finally, when it comes time to compile these documents for delivery,
it is a tedious process to arrange the correct documents in the correct order
without any unexpected issues. Also, I think an issue that has come up in this
release that also appeared in this release is that the links in the generated
PDF files did not work.

A better approach to documentation would:

First and foremost be able to compile all existing documentation with a single
command. There is really no good reason to have so many steps for human
intervention, and hence mistakes since it should be possible, in both theory
and practice, to have a simple working PDF produced with a single command.
Furthermore, there is really no good reason for us to tie our documentation to
a proprietary product, like Microsoft Word. Especially since we are an open
source project. 

Second, we should be able to edit documentation without any software besides a
web browser. By easing the overhead of updating documentation, we are much
liker to have documentation that is updated more often, to be more accurate,
and of a higher quality. I believe that there might be solutions out there that
allow the editing of documentation by anyone from a web browser (something like
Wikibooks might do the trick, but more research is necessary). If we found a
way to allow the documentation to be edited from the browser, this would make
it easier to update the documentation as we work and also in response to
questions we get from the community. Also, it would allow more people to be
able to easier contribute to the documentation, whether or not they have
Microsoft Word, whether or not they know how to access our repositories to
access the current documentation and whether or not they could figure out how
our current documents are structured and whether or not they have write access
to our SVN repository.

Perhaps getting documentation that is fully editable from any browser is
unrealistic. It depends on the adequacy for our needs of open source projects
(like Wikibooks) and also how much effort would be involved to take our current
documentation from Microsoft Word format into the more open formats supported
by these projects. But at the very least, we should strongly consider at least
moving away from solutions that require access to proprietary software and
which are error prone when converting from the format in which documents are
written into their final form.

-- 
Configure bugmail: http://bugzilla.ecoinformatics.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.