Making more documentation faster with wiki

The documentation is actually 100% docbook based. Docbook are converted to SVG for integrated tutorials if I'm not wrong.
The problem is docbook is not the easiest way to make a doc for everyone, and there are lot of people that are not developers and would like to help for some other tasks (as we see lot of good free tutorials around the web and translator in lot of languages).
Actually the manuals are here in Inkscape SVN, there is an English and a French beginning of doc : http://inkscape.svn.sourceforge.net/viewvc/inkscape/user_manual/trunk/xml/
The doc didn't move since one month, Elisa-Yemanja (that already amade a paper book manual on Inkscape) contributed in French version 2 weeks ago, but think this is too long process to manage docbook.
I think it will be better to use a well defined wiki for manual, as lot of contributors could participate easly as wikimedia projects and some other projects shown. There are already started wikibooks for inkscape on wikibooks.org.
I believe there are 2 conditions for this project to be used: * A well defined zone for the wikimanual doc (like doc.inkscape.org, manual.inkscape.org or inkscape.org/doc), actually user have to dig in wiki to find part of user information. * Tools to convert automatically this wiki to docbook.
I then searched tools to convert from wiki to docbook and from docbook to wiki, and there are several ones: to integrate docbook to wiki (and don't restart the whole documantation) there are scripts made by blender.org (or at least referenced on there wiki) in perl and python : http://wiki.blender.org/index.php/Meta/DocBook_to_Wiki
mediawiki project itself contain a php wiki2docbook, available in the mediawiki svn (and archive, I suppose): http://tools.wikimedia.de/~magnus/wiki2xml/w2x.php
Example of conversion to odt et pdf are nice they even contain link to other pages of the manual on the de.wikipedia.org used as example: http://www.nabble.com/Wiki-Konverter-to3627646.html
I suppose we could output to SVG from docbook and change to local disk pages or other site obtaining then a full doc separated distribution (as there is gimp + gimp-doc, python + python-doc, ruby + ruby-doc, ...) or choose to make links to generated svg doc on inkscape site or both, to have well done manual for users with interactive features as actual tutorials. I think tutorial is good as is light, allowing a quicktour to Inkscape, the doc should be another documentation separated from inkscape itself, at least in a first time.
There are other wiki2XML in Perl (including docbook converter) here: http://search.cpan.org/search?query=wikiformat&mode=all
General wiki format, Text::Wikiformat : http://search.cpan.org/~chromatic/Text-WikiFormat-0.79/lib/Text/WikiFormat.p...
And specialized mediawiki format Text::MediawikiFormat: http://search.cpan.org/author/DPRICE/Text-MediawikiFormat-0.05/lib/Text/Medi...
CGI::Kwiki and Pod::Simple::Wiki are other Perl parser.
There is to dig here for Python parsers/converters: http://pypi.python.org/pypi?%3Aaction=search&term=wiki+docbook&submi...
A Ruby converter from wiki to docbook (and other) : http://rubyforge.org/projects/deplategem/ Ruby wiki parsers : http://rubyforge.org/search/?type_of_search=soft&words=wiki+docbook&...
Regards,
Popolon

I think this is a good idea.
Whereas I do not think a wiki would be a replacement for a well-written manual, it would be a much more accommodating media for those of us who don't know docbook well, and would encourage more contribution. While I would not think that the wiki and manual would ever be in sync (since the wiki would be perpetually and "arbitrarily" changing), I think the two would compliment each other very well.
I know that people can (and do) post some user documentation on the current wiki, but it really isn't well separated or easily accessible. I think maybe a wiki at docs.inkscape.org dedicated to user-support info would be very nice. Maybe sectioned off into how-tos, tutorials, etc, with links to the existing docs (or even hosting them directly, if they can be kept distinct enough).
However, as I mentioned, I really don't think the two (wiki and manual) forms of docs are mutually exclusive or the same thing. I really think they should remain separate entities.
Has this possibility been discussed before?
JF
popolon@...1497... wrote:
The documentation is actually 100% docbook based. Docbook are converted to SVG for integrated tutorials if I'm not wrong.
The problem is docbook is not the easiest way to make a doc for everyone, and there are lot of people that are not developers and would like to help for some other tasks (as we see lot of good free tutorials around the web and translator in lot of languages).
Actually the manuals are here in Inkscape SVN, there is an English and a French beginning of doc : http://inkscape.svn.sourceforge.net/viewvc/inkscape/user_manual/trunk/xml/
The doc didn't move since one month, Elisa-Yemanja (that already amade a paper book manual on Inkscape) contributed in French version 2 weeks ago, but think this is too long process to manage docbook.
I think it will be better to use a well defined wiki for manual, as lot of contributors could participate easly as wikimedia projects and some other projects shown. There are already started wikibooks for inkscape on wikibooks.org.
I believe there are 2 conditions for this project to be used:
- A well defined zone for the wikimanual doc (like doc.inkscape.org,
manual.inkscape.org or inkscape.org/doc), actually user have to dig in wiki to find part of user information.
- Tools to convert automatically this wiki to docbook.
I then searched tools to convert from wiki to docbook and from docbook to wiki, and there are several ones: to integrate docbook to wiki (and don't restart the whole documantation) there are scripts made by blender.org (or at least referenced on there wiki) in perl and python : http://wiki.blender.org/index.php/Meta/DocBook_to_Wiki
mediawiki project itself contain a php wiki2docbook, available in the mediawiki svn (and archive, I suppose): http://tools.wikimedia.de/~magnus/wiki2xml/w2x.php
Example of conversion to odt et pdf are nice they even contain link to other pages of the manual on the de.wikipedia.org used as example: http://www.nabble.com/Wiki-Konverter-to3627646.html
I suppose we could output to SVG from docbook and change to local disk pages or other site obtaining then a full doc separated distribution (as there is gimp + gimp-doc, python + python-doc, ruby + ruby-doc, ...) or choose to make links to generated svg doc on inkscape site or both, to have well done manual for users with interactive features as actual tutorials. I think tutorial is good as is light, allowing a quicktour to Inkscape, the doc should be another documentation separated from inkscape itself, at least in a first time.
There are other wiki2XML in Perl (including docbook converter) here: http://search.cpan.org/search?query=wikiformat&mode=all
General wiki format, Text::Wikiformat : http://search.cpan.org/~chromatic/Text-WikiFormat-0.79/lib/Text/WikiFormat.p...
And specialized mediawiki format Text::MediawikiFormat: http://search.cpan.org/author/DPRICE/Text-MediawikiFormat-0.05/lib/Text/Medi...
CGI::Kwiki and Pod::Simple::Wiki are other Perl parser.
There is to dig here for Python parsers/converters: http://pypi.python.org/pypi?%3Aaction=search&term=wiki+docbook&submi...
A Ruby converter from wiki to docbook (and other) : http://rubyforge.org/projects/deplategem/ Ruby wiki parsers : http://rubyforge.org/search/?type_of_search=soft&words=wiki+docbook&...
Regards,
Popolon
This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2005. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel

I agree with you JF.
It's very heavy to write in the docbook.
And thank for the idea Popolon.
Elisa
Le Saturday 05 January 2008 00:21:45 Joshua Facemyer / Impressus Art, vous avez écrit :
I think this is a good idea.
Whereas I do not think a wiki would be a replacement for a well-written manual, it would be a much more accommodating media for those of us who don't know docbook well, and would encourage more contribution. While I would not think that the wiki and manual would ever be in sync (since the wiki would be perpetually and "arbitrarily" changing), I think the two would compliment each other very well.
I know that people can (and do) post some user documentation on the current wiki, but it really isn't well separated or easily accessible. I think maybe a wiki at docs.inkscape.org dedicated to user-support info would be very nice. Maybe sectioned off into how-tos, tutorials, etc, with links to the existing docs (or even hosting them directly, if they can be kept distinct enough).
However, as I mentioned, I really don't think the two (wiki and manual) forms of docs are mutually exclusive or the same thing. I really think they should remain separate entities.
Has this possibility been discussed before?
JF
popolon@...1497... wrote:
The documentation is actually 100% docbook based. Docbook are converted to SVG for integrated tutorials if I'm not wrong.
The problem is docbook is not the easiest way to make a doc for everyone, and there are lot of people that are not developers and would like to help for some other tasks (as we see lot of good free tutorials around the web and translator in lot of languages).
Actually the manuals are here in Inkscape SVN, there is an English and a French beginning of doc : http://inkscape.svn.sourceforge.net/viewvc/inkscape/user_manual/trunk/xml /
The doc didn't move since one month, Elisa-Yemanja (that already amade a paper book manual on Inkscape) contributed in French version 2 weeks ago, but think this is too long process to manage docbook.
I think it will be better to use a well defined wiki for manual, as lot of contributors could participate easly as wikimedia projects and some other projects shown. There are already started wikibooks for inkscape on wikibooks.org.
I believe there are 2 conditions for this project to be used:
- A well defined zone for the wikimanual doc (like doc.inkscape.org,
manual.inkscape.org or inkscape.org/doc), actually user have to dig in wiki to find part of user information.
- Tools to convert automatically this wiki to docbook.
I then searched tools to convert from wiki to docbook and from docbook to wiki, and there are several ones: to integrate docbook to wiki (and don't restart the whole documantation) there are scripts made by blender.org (or at least referenced on there wiki) in perl and python : http://wiki.blender.org/index.php/Meta/DocBook_to_Wiki
mediawiki project itself contain a php wiki2docbook, available in the mediawiki svn (and archive, I suppose): http://tools.wikimedia.de/~magnus/wiki2xml/w2x.php
Example of conversion to odt et pdf are nice they even contain link to other pages of the manual on the de.wikipedia.org used as example: http://www.nabble.com/Wiki-Konverter-to3627646.html
I suppose we could output to SVG from docbook and change to local disk pages or other site obtaining then a full doc separated distribution (as there is gimp + gimp-doc, python + python-doc, ruby + ruby-doc, ...) or choose to make links to generated svg doc on inkscape site or both, to have well done manual for users with interactive features as actual tutorials. I think tutorial is good as is light, allowing a quicktour to Inkscape, the doc should be another documentation separated from inkscape itself, at least in a first time.
There are other wiki2XML in Perl (including docbook converter) here: http://search.cpan.org/search?query=wikiformat&mode=all
General wiki format, Text::Wikiformat : http://search.cpan.org/~chromatic/Text-WikiFormat-0.79/lib/Text/WikiForma t.pm
And specialized mediawiki format Text::MediawikiFormat: http://search.cpan.org/author/DPRICE/Text-MediawikiFormat-0.05/lib/Text/M ediawikiFormat.pm
CGI::Kwiki and Pod::Simple::Wiki are other Perl parser.
There is to dig here for Python parsers/converters: http://pypi.python.org/pypi?%3Aaction=search&term=wiki+docbook&submi... rch
A Ruby converter from wiki to docbook (and other) : http://rubyforge.org/projects/deplategem/ Ruby wiki parsers : http://rubyforge.org/search/?type_of_search=soft&words=wiki+docbook&... h=Search
Regards,
Popolon
This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2005. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2005. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel

Very good!
(the Inkscape-Brasil community uses wiki (TWiki) to everything)
A web documentation is better to use/navigate then a SVG inside the ink. A pretty docs wiki can be a big help for a lot of people.
For this we can think in pages and sub-pages of documentation on the wiki for a better navigation and wiki editation. To create the doc-books all sub-pages can be joined before the format translation.
:-) Aurium
On Jan 4, 2008 4:57 PM, <popolon@...1497...> wrote:
(...) I think it will be better to use a well defined wiki for manual, as lot of contributors could participate easly as wikimedia projects and some other projects shown. There are already started wikibooks for inkscape on wikibooks.org.
I believe there are 2 conditions for this project to be used:
- A well defined zone for the wikimanual doc (like doc.inkscape.org,
manual.inkscape.org or inkscape.org/doc), actually user have to dig in wiki to find part of user information.
- Tools to convert automatically this wiki to docbook.
(...)
Regards,
Popolon

If nobody has any objections, can we do this? Who would be the person to do the installation? It might be a really great thing to announce with the release announcement, which could excite people to contribute as they try out the new features.
JF
Aurélio A. Heckert wrote:
Very good!
(the Inkscape-Brasil community uses wiki (TWiki) to everything)
A web documentation is better to use/navigate then a SVG inside the ink. A pretty docs wiki can be a big help for a lot of people.
For this we can think in pages and sub-pages of documentation on the wiki for a better navigation and wiki editation. To create the doc-books all sub-pages can be joined before the format translation.
:-) Aurium
On Jan 4, 2008 4:57 PM, <popolon@...1497...> wrote:
(...) I think it will be better to use a well defined wiki for manual, as lot of contributors could participate easly as wikimedia projects and some other projects shown. There are already started wikibooks for inkscape on wikibooks.org.
I believe there are 2 conditions for this project to be used:
- A well defined zone for the wikimanual doc (like doc.inkscape.org,
manual.inkscape.org or inkscape.org/doc), actually user have to dig in wiki to find part of user information.
- Tools to convert automatically this wiki to docbook.
(...)
Regards,
Popolon

On Jan 6, 2008 10:21 PM, Joshua Facemyer / Impressus Art wrote:
If nobody has any objections, can we do this? Who would be the person to do the installation? It might be a really great thing to announce with the release announcement, which could excite people to contribute as they try out the new features.
You might have missed my email to inkscape-docs :)
Alexandre

Don't know if anyone has seen the following; http://www.xmlmind.com/xmleditor/ http://www.xmlmind.com/xmleditor/
This seems to be a fairly easy free and cross-platform solution.
This page also mentions that link, but suggests that you can use Open Office 2.x to edit DocBook docs; http://www.cytoscape.org/cgi-bin/moin.cgi/How_to_update_the_Cytoscape_manual... http://www.cytoscape.org/cgi-bin/moin.cgi/How_to_update_the_Cytoscape_manual...
Perhaps this will help until another solution comes along (?).
participants (6)
-
unknown@example.com
-
Alexandre Prokoudine
-
Aurélio A. Heckert
-
Elisa
-
Joshua Facemyer / Impressus Art
-
rygle