[osiris-devel] 3.0.4-current development documentation?

[Alexei Roudnev]

Thomas; I did not proposed to help with documentation _only_ because English
is not my native language. I wrote a huge amount of technical documentation
in my life. So, I have some background for my opinion (as I was saying, I do
not insist about xml etc, through it's importance is overestimated).

If you open any _good_ project, such as QT, you will see the same approach -
documentation files are part of the project (cvs-ed etc) but are separated,
on level 1 and level-2, from the source files. level-3 (function XXX,
parameters, return, short description) is kept inside source files.

If you are intending, that Sun (who uses JavaDoc approach) provides _GOOD_
documentation, then I am very sorry.

Alex

----- Original Message ----- 
From: "Thomas Jones" <thomas.jones at linux-howtos.com>
To: <osiris-devel at lists.shmoo.com>
Sent: Sunday, February 22, 2004 2:30 AM
Subject: Re: [osiris-devel] 3.0.4-current development documentation?


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sunday 22 February 2004 15:39, Alexei Roudnev wrote:
> Sorry, Tom. Of course, it is not a bad idea, and it is only a _disk space_
> issue.
>
> But remember, that 99% of all users do not need your xml, dtd etc - they
> need plain text on the screen, so pdf file or html file looks quite enough
> for the _binary_ distribution. Anyway, it's not important, I have not any
> objections.
>
> Doxigen (JavaDoc etc) is quite another issue. In  real projects, it is not
> _redundant_. Reason is very simple: - documentation is edited and
corrected
> by _technical editor_, _technical corrector_ etc; - you do not want them
to
> edit a sources;
> - you do not want to have a include file, having 90% of the documentation
> and 10% of the source code.
>
<snip>

I am a Technical Education Specialist for a Fortune 500 company ----- I am
pretty sure that i understand the theory behind technical documentation
procedures and/or processes.

If you had noticed, I made the comment that the core developers utilize
JavaDoc. This was not posted to the User List. Thus, it is a generally
accepted as a reasonable request for technical individuals.

I think you may be getting the standard documentation procedures confused
and/
or integrated with your backward way of processing data. The whole process
you ranted about is simply useless. You again are highly confused; and
elaborate exceedingly about irrational ways to perform various procedures.
Even though they(standard procedures) are widely accepted by the developemnt
community.

Here are a couple example highlights:

 - But remember, that 99% of all users do not need your xml<snip>
This is a development reference, on a development list. Enough said.

- - .cpp and .h files, used to generate detailed references to the api
functions.
Doesn't ALL documentation "generator's"; utilize the same files as above?

- - a mess of 90% useless reference manuals
Any documentation that applies to the referenced material is not useless. It
may very well be beyond the scope of your knowledge; but to other more
advanced developers it is very efficient.

Rather than providing your unorthodox ways of performing various procedures;
it would considerably easier if you were to just make contributions to the
project in the areas that you feel you are exceedingly qualified.

Thomas
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQFAOITHQT2komo99ukRAjYNAJ41d7K0QyXsOPWHoygYw0q2GjrOuACgoSXf
sCAARaScWFNNIpip+k0gBXM=
=N5HH
-----END PGP SIGNATURE-----

_______________________________________________
osiris-devel mailing list
osiris-devel at lists.shmoo.com
https://lists.shmoo.com/mailman/listinfo/osiris-devel