[Trisquel-devel] Documentation Team/Organization

[Luis Felipe López Acevedo]

I'd like to share with you my idea about writing documentation.

Basically, I'd like to write in a format from which you could create online
and offline versions. The former could be used in the website, the latter
could be included in the distro for users without Internet connection (I
live in Colombia, I know many of this kind of user).

I made an example of documentation written in such a format (Mallard) so
that you can judge from it. A fictional distribution is used in this
example: DistroName; and the following are the files used to write the
documentation.


   1. Source files: The source files are available in a repository where all
   writers commit their changes (https://github.com/IntrosMedia/DistroHelp).
   2. HTML files: The help documentation generated from source files and
   available online for final users (
   http://nihongokit.tuxfamily.org/help/en/).
   3. Debian file: The final documentation written in mallard and packaged
   for distribution with DistroName. If you install this, it will create a new
   entry in Main menu → Education → DistroHelp, so that you can try out the
   documentation as a local help system. You can uninstall it as with any other
   package (
   http://download.tuxfamily.org/introsmedia/documentos/distrohelp_0.1.0-1_all.deb).
   Of course, if it was used in a real distro, you would access the
   documentation from the System menu.


Mallard is one of the formats used by Yelp (the default help browser in
GNOME) to display local help documentation. Yelp has some tools to convert
Mallard documents to HTML.

In the example documentation I suggest a structure that I'd like to see in
Trisquel documentation.

Using a repository could help writers branch the current documentation to
adapt it to new versions of the distro. Currently, in Trisquel wiki you
don't know if the documentation is written for this or that version of
Trisquel.

I think that's all.

Cheers,

-- 
Luis Felipe López Acevedo
IntrosMedia <http://introsmedia.wordpress.com/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listas.trisquel.info/pipermail/trisquel-devel/attachments/20110120/a2cb86d0/attachment.htm>