Kepler: Issueshttps://projects.ecoinformatics.org/ecoinfo/https://projects.ecoinformatics.org/ecoinfo/ecoinfo/favicon.ico?14691340362011-03-22T00:40:30ZEcoinformatics Redmine
Redmine Bug #5354 (New): Integrate Kepler Wiki Into Kepler Helphttps://projects.ecoinformatics.org/ecoinfo/issues/53542011-03-22T00:40:30ZDavid Welkerdavid.v.welker@gmail.com
<p>Sven has an idea. When running Kepler, there should be two types of help. One for users and one for developers. Both should be accessible from the Help menu, and should reference appropriate places on the Kepler wiki. This should be integrated with the current help information all of which should be organized in a logical manner.</p> Bug #5327 (New): Need to fix documentation systemhttps://projects.ecoinformatics.org/ecoinfo/issues/53272011-02-25T23:38:36ZDavid Welkerdavid.v.welker@gmail.com
<p>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.</p>
<p>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.</p>
<p>A better approach to documentation would:</p>
<p>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.</p>
<p>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.</p>
<p>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.</p> Bug #5173 (New): Develop clear criteria for when code in Kepler CORE should be in its own module.https://projects.ecoinformatics.org/ecoinfo/issues/51732010-09-08T23:24:18ZDavid Welkerdavid.v.welker@gmail.com
<p>As of now, we have broken up Kepler into a number of modules. But this breaking up of Kepler has been ad hoc and not followed a consistent set of guidelines concerning when code should be in its own module and when it should be grouped with other code that is somehow related in a common module.</p>
<p>Lack of consistent guidelines make modules harder to understand. Following more consistent guidelines would make Kepler easier to understand.</p>