| Version 1 (modified by , 11 years ago) ( diff ) |
|---|
GRASS Wiki versus Trac Wiki
Table of Contents
This page discuss what information should go to the GRASS Wiki and what to the Trac Wiki.
- http://grasswiki.osgeo.org/ (GRASS Wiki, GRASS GIS Users Wiki, MediaWiki)
- https://trac.osgeo.org/grass/wiki (Trac Wiki, GRASS GIS Tracker and Wiki, TracWiki)
GRASS Wiki for current things
The idea is that GRASS Wiki should be used just to describe things as they are. No discussions, no wishes, no proposals.
The GRASS Wiki should be something like user added manual. It should contain specific examples with specific data. Guides how to use GRASS with some particular software, technology, service or data source. It should be a collection of use cases.
GRASS Wiki should not contain proposals and pages serving as a notebook supporting development. Example of an inappropriate page is page Toolboxes:
http://grasswiki.osgeo.org/grass-wiki/index.php?title=Toolboxes&oldid=18005
The end user should not be confused by pages about things which does not exists. When he or she would come to Toolboxes page above, he or she expects to learn about what toolboxes in GRASS are not what they could be if the would be implemented in this or that way.
Trac Wiki for developing ideas and tracking development
Trac Wiki is the one which should be used to support development as it is connected more to tickets, commits and source code and in the same time, it is clear that it is something different than manual or GRASS wiki, so this could help to avoid confusion. For example, there is no point in having Single Map window idea listed among the existing wxGUI components at GRASS Wiki while the page at Trac wiki is perfectly OK:
https://trac.osgeo.org/grass/wiki/wxGUIDevelopment/SingleWindow
Controversy: Moving pages from Trac
The result of the above is also that the pages such as
https://trac.osgeo.org/grass/wiki/Grass7/NewFeatures
and partially also
https://trac.osgeo.org/grass/wiki/DownloadSource
should be moved to GRASS Wiki because they are describing things which are important to users and describes current status.
The only pages on Trac Wiki which describes state of art should be the pages how to use Trac itself, for example:
https://trac.osgeo.org/grass/wiki/HowToUseKeywords
Controversy: Manpower for moving pages
For the moving of pages we need the manpower which we lack according to the fact that we were not able to do any of the wikis cleanups which were already planed. However, by continuing in the current way where there are no rules what to put where, we are just creating more work for the future.
So, we don't have to start to move pages around now, but it is advisable to keep the rules and think twice about what should be where.
Controversy: GSoC
GSoC pages are in the group of nice pages at GRASS Wiki and there is a tradition of putting them there, for example
http://grasswiki.osgeo.org/grass-wiki/index.php?title=GRASS_SoC_Ideas_2013&oldid=18760
However, the page lists things which could be done. Most of the ideas are not even turned into proposals, so why again, describe nonexistent things there?
The same applies to student pages, too. For example temporal algebra has the page for developing ideas (and some temporary documentation) at the Trac Wiki:
http://trac.osgeo.org/grass/wiki/Grass7/TemporalGISAlgebra
That is great. However, the student notes
are in fact developer notes which should be on Trac, too: they describe the progress, they are more or less commit messages. Why the user would be interested in this if it is not in the code, and current status is maybe completely different?
Controversy: GRASS Wiki for development
One of the biggest questions is if the pages about how to develop for GRASS should go to GRASS Wiki. The answer is yes, these pages describe how things are, so they should go GRASS wiki and not Trac Wiki because Trac Wiki which does not describe API or how to use it.
We already converged to having "How to compile" pages on GRASS wiki (they were marked "move to trac" at one point, but not now). We also have a lot of pages about scripting there. And from scripting is just one step to programming (from bash to grass.script to pygrass/ctypes to C or wxGUI), so there is no reason to not include it on the GRASS Wiki. Moreover, where would be the line between using GUI or modules in command line and programming when Python console is the part of GUI?
The scripting is the typical half-user half-developer topic:
Controversy: GRASS Wiki is not manual
When excited about what we can put the GRASS Wiki and making it right, we must remember the fact that we have also manual, more precisely, two manuals. So, create pages, enjoy user edits but think about the fact that the basic things should be in the manual.
For example, see page about inputs to a module which is at the wiki:
Explanation of parameters and preparing input is certainly the basic topic which should be moved to manual. In other words, if the page on GRASS Wiki describes something so well that it is better than manual or the module is useless without the page, the page should be moved to manual.
For things such as best practices and development, the things can be more complicated than for modules but the general pattern is clear, general things may appear at GRASS Wiki but when mature enough, they should be moved manual because otherwise GRASS Wiki would be replacing manual (and the next logical step would be to remove manual pages and programming manual).
Controversy: Different syntax
At some points it seemed that GRASS Wiki is preferred over the Trac one because the Trac wiki has different syntax. But the issue is not so bad. As a developer or power user one must deal not only with WikiMedia syntax but also with HTML for manual pages and Doxygen for programming manual, so one syntax more (TracWiki syntax) is probably not a problem. Moreover, (Trac) WikiFormatting is need for Trac tickets and both tickes and wiki have Preview button and hopefully some day, we will see the new Trac version with live preview.
