[Lazarus] Missing Documentation

[Frank Church]

On 28 February 2012 18:43, Marc Santhoff <M.Santhoff at web.de> wrote:

> Hi again,
>
> since there were multiple complaints about missing documentation, where
> can I find a list of what is missing exactly in detail?
>
> Is there a wiki page about it? Or a docs page collecting empty
> descriptions or the like?
>
> Sometimes I'm bored, maybe there are items I'm able to add
> a couple of useful words to ...
>
> TIA,
> Marc
> --
> Marc Santhoff <M.Santhoff at web.de>
>
>
> --
> _______________________________________________
> Lazarus mailing list
> Lazarus at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>

I asked this question in the FPC mailing list a few hours ago, and I am
here to ask the same question about Lazarus. Hopefully I won't press the
Send button in Gmail before I finish.

It is becoming obvious as shown in this thread that good documentation
about Lazarus Documentation and more importantly the process, tools and
procedures by which it is generated is lacking and that together with some
documentation about how the Lazarus project itself is organized is
necessary before any meaningful and friction free progress can be made. I
have thought about starting a new thread but this one seems as good as any.



1. Are they created by a tool or hand edited? what are the tools used?

2. Is there some page where the original docs are created?

3. Are they text files that are stored under version control?

4. Is there some page where previous versions are available?

5. How is it structured, what are the formatting rules? Is based on
standards like DocBook etc?

6. How much of the documentation is generated from the source code? Is
information about input and output parameters, and a few lines about its
usage and gotchas generated from source, or does all procedures need to be
documented by hand using FPDoc? Graeme mentions IPF that in his view does a
better job? Do other preferably Pascal based projects use other tools with
which they have had more success?

7. Are there other tools that can do a better job, such as Jira, Github etc?

8. I assume that docs are generated by some build tool once created. Does
the submitter compile the docs on their own system and test that they are
fine before getting them committed into the repository? Are the tools used
identical (I see messages in the mailing list about contributors being
using different versions of the tools)?

I guess these are the questions I want to ask.



-- 
Frank Church

=======================
http://devblog.brahmancreations.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20120229/ac2ba155/attachment-0003.html>