Re: [ros-dev] Documentation

[Marc Piulachs]

Hi All,

A part from the documentation generated by the developers I think we should
start thinking about the End-User documentation.

Having complete and localized end user documentation (winhelp/htmlhelp) for
every application will take years so never is too early to start and a lot
of non developer community members can contribute.

My proposal is to place the documentation in a standardized folder in every
module in the source tree for example "docs" or "help"

The most obvious choice for me is to use docbook (see
http://www.codeproject.com/winhelp/docbook_howto.asp for an introduction to
docbook) 

The idea is to use a different file for every language, for example:

\base\applications\calc\help\en-US.xml
\base\applications\calc\help\es-Es.xml
....

Then we can add a new tag to rbuild to generate the end-user documentation
in any format we desire (man , winhelp , htmlhelp or plain html to publish
on the web) as part of the standard build. Something like that:

<directory name="help">
	<helpfile locale="en-US">en-US.xml</helpfile>
	<helpfile locale="es-ES">es-ES.xml</helpfile>
</directory>

It seems a simple solution to implement.

Marc,

-----Original Message-----
From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On
Behalf Of Colin Finck
Sent: Wednesday, September 19, 2007 7:34 PM
To: ros-dev(a)reactos.org
Subject: [ros-dev] Documentation

Hello,

Recently, some developers wrote documentation about certain stuff related to
ReactOS.
But this documentation was only placed on their own web servers.

In my opinion, it would be better if such stuff would (also) be committed to
the "documentation" directory in SVN.
Having documentation there makes sure that it does not get lost.
Additionally, if the source file is committed (not a PDF or something like
that), another person could extend the documentation further.
I agree that not all documentary stuff needs to be on SVN. An example might
be Magnus' Win32k syscall tables.
But for example Andrew Greenwood's documentation about the Windows
Multimedia Subsystems looks like something, which should be committed in my
opinion.

If you don't agree on committing this stuff, it would be nice if we could at
least agree on an official document format, which should be used in the SVN
tree.
>  From what I see, most documentations were created by
> using OpenOffice, so I 
think the OpenDocument Text format (ODT) would be a great
choice. It is also
supported by most word processors, thus most people should be able to open
an ODT file.
Up to now, I used RTF for formatted text documentations in SVN, but this
format does not support things like shapes.

Regards,

Colin

_______________________________________________
Ros-dev mailing list
Ros-dev(a)reactos.org
http://www.reactos.org/mailman/listinfo/ros-dev