Hi all
I would like to help to make Official Harbour Documentation a reality. You
have been done an excelent coding job here and harbour could be much more
appreciated and enjoyed (yet) with a proper official documentation within.
Unfortunatelly I have been following that writing Official Harbour
Documentation counts on few cabable heads and requires a much more of their
two hands to be done.
I am not sure of how and if this problem can be solved, but I feel like it
worths the try to solve it, so I invite you to consider the execution of the
following strategy: to form a Harbour Documentation Task Force.
The Harbour Documentation Task Force would be conducted by at least 4 people
on the following roles:
1 - Doc Writing Supervisor: writing productivity and the technical quality
control of the document writing;
2 - Doc Tools Supervisor: development control of harbour documentation
management tools;
3 - Doc Publishing Manager: gramatic and ortografic quality control of the
documents, distribuition media and publishing management;
4 - General Coordinator: synchronize and coordinate the work of the 3 task
forces;
Task force 1 - Doc Writing
The only goal of this task force is the most important of all: to write the
text of the harbour documentation. The basic need to acomplish this task is
human resources. So to be done this job needs a list of capable volunteers
to write the text of the documentation. Considering the huge amount of code
to be documented, this task has to be structured in topics. To minimize the
debate about how such topic structure should be or look like, the same
structure of harbour/src folder could be assumed as the list of topics for a
start. Following such logic, documentation writing task would be distributed
between Doc Writing Teams, each of which responsible for documenting one or
more of the following code 14 topics:
1 - Codepage
2 - Common
3 - Compiler
4 - Debug
5 - Dynlib
6 - Hbextern
7 - Lang
8 - Macro
9 - Main
10 - Nortl
11 - PP
12- RDD
13 - RTL
14 - VM.
There must be chosen a Doc Writing coordinator to synchronize this task to
the general chronogram and supervise the quality of the writing. The first
job this person should take care could be the calculation of how many teams
(of how many people each) should be necessary to write the documentation of
above 14 topics, considering the technical
afinity among some of the topics and their weight differences, once some can
have much more to be documented than others. Once that is defined, the
following job would be to recruit such amount of volunteers and allocate
them to their tasks.
Task force 2 - Doc Tools
This task force would initially develop a tool to make Doc Writing more
organized and productive. Such tool should initially provide :
1 - documentation task status, comparing of harbour source files to harbour
document files, classified by source folder;
2 - easy and simple interface to edit documents, so writers don't need to
know or care about folders, files, markers etc, only about the text;
3 - document status control interface, where Doc Writing coordinator can
sinalize and Doc Writers can see what documents are (and weather each
document is) done, not started, incomplete or not good;
Much of what it takes to provide the above goods seems to have been already
achieved by Vailton using Delphy and of course they can be done also using
Harbour. I'm sure this is the task force that can be formed earlier, because
most people here can code, but we must consider that, without a capable team
responsible for writing the docs there is not much sense to build such
tools. Anyway, I believe the the 1st item could help very much on the work
Doc Writers recruiting, because once people know what exactly is to be
written on each topic, it would be easier that they can candidate to write
about this and that and maybe this task should be done in first place
anyways.
Of course a lot of other things sure would be asked from Doc Tools team in
future, but I believe the above would be enough for the beginning.
Task force 3 - Doc Publishing
This task force would be responsible for determining the better distribution
formats and publishing media and care for the gramatical and ortografical
quality of the document text, as weel as all the aesthetic and text style
considerations. Of course some of this job can be started right away, but
sure its no sense at all to talk much about it before the documents start to
be written.
Sorry if I this was inconvenient and let me know if there is something else
I can do to help.
Best regards to all
Leandro
--------------------------------------------------
From: "Bacco" <carlosba...@gmail.com>
Sent: Friday, February 19, 2010 9:56 AM
To: "Harbour Project Main Developer List." <harbour@harbour-project.org>
Subject: Re: [Harbour] Re: About Harbour Documentation
On Fri, Feb 19, 2010 at 08:27, Vailton Renato <vail...@gmail.com> wrote:
Hi!
I developed an tool some months ago that reads all the source code on
folder /harbour/src + /harbour/contrib and compare it with the
existing documentation in /harbour/doc and show me what has documented
and what source files are modified. This tool works as a visual
front-end to edit the documentation in the form NF.
Is this tool in Delphi too? I dont know if we was thinking the same
thing, but anyway If yours are in Delphi I still want to do on mine,
maybe some part can be used on HBIDE. As both tools work in NanForum
format, both tools can be useful without conflicts. I am really
focusing on easy of use, handling of all TXTs in doc/LANG and
contrib/HBNNN/doc/LANG folders without manual loading, and
multilanguage, but mine is starting and yours seems to be done. At
least, with your tool and directly into the TXTs maybe someone can
start writing documentation right now.
Additionally wrote an application that reads the format NF and exports
to HTML + CSS into an format to integrate the project site ... I just
did it as temporary tool, specific to this need and I developed it in
Delphi (which is a language I know well) to run on my CPU with Windows
and for my needs it is helping me as well, although it lacks some
details to be completely ready .
Since I could not waste time because our time is short, I opted for
that for me it was faster ... Do you think this could be useful in
this process?
I was thinking about parse into a database for the web, like mysql+php
so we can search for commands online and so on, but this is a future
step. For me, the lack of documentation is the true problem. As you
already have this temporary tool, I believe that you can use it and
share the result files somewere while we don't have another ready for
use.
Regards,
Vailton Renato
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
Harbour@harbour-project.org
http://lists.harbour-project.org/mailman/listinfo/harbour
Finally, If anyone really want to write documentation, there is no
reason to wait for any tool, it's just a matter of pick up any text
editor and start writing. Converting it into any other format after is
the easy part. Nothing that copy+paste and some little formating won't
do (just my opinion, anyway).
Regards
Bacco
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
Harbour@harbour-project.org
http://lists.harbour-project.org/mailman/listinfo/harbour
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
Harbour@harbour-project.org
http://lists.harbour-project.org/mailman/listinfo/harbour
