Hi
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 cabaple heads and requires a lot more 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 three
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: 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, rdd, rtl and 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 would be to recruit such amount of volunteers and allocate them to
their tasks.
Task force 2 - Doc Editing Tool
This task force would initially develop a tool to make Doc Writing more
organized and productive. Such tool should 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 seems to have been already
achieved by Vailton using Delphy and they can be written in harbour.
--------------------------------------------------
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
