Hi all
I would like to help to make Official Harbour Documentation a reality.
Harbour Developers have been doing an excelent coding job here and Harbour
Project could be much more appreciated and enjoyed with a proper official
documentation. Unfortunatelly I have been following that writing Official
Harbour Documentation counts on few capable heads and requires a much more
than their two hands each 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 Manager: technical quality and productivity control of the
document writing;
2 - Doc Tools Manager: functional quality and productivity control of
harbour documentation management tools development;
3 - Doc Publishing Manager: language control of the documents, distribuition
media and publishing management;
4 - Doc Task Coordinator: guide and synchronize the 3 task forces;
Task force 1 - Doc Writing
The only goal of this task force is the most important of all: write the
text of the harbour documentation. The only resource to acomplish this task
is capable and available people. So, to be accomplished, this task needs a
list of technically capable volunteers to write the text of the
documentation and a list os volunteers to rewrite compatible documentation
from other sources. 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, 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 care for the technical quality of the writing.
The first job this person should do would be to raise what is to be written
and calc how many teams (of how many people each) should be necessary to
document the 14 topics above, 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 part of documentation was already written
for others thanks to compatibility with Clipper it doesn't have to be
reformulated, so if it cannot be directly incorporated to the doc
repository, it should be manually read and retyped on text files - and to do
that one doesn't get to know much about harbour internals, so many people
could help on this. Once the size of the work is delimited and distribuited
between the needed teams , the following job would be to recruit such amount
of volunteers and allocate them to their jobs.
Task force 2 - Doc Tools
This task force would initially develop a tool to help Doc Writing Task
Force on workflow uniformity, productivity and control. 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 there will be plenty of volunteers to this task force,
because most people oh the list codes very well, 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 above could
help very much on Doc Writers recruiting, because once people know what
exactly is to be written about each topic, it would be easier to manage the
recruiting and volunteers could candidate to write about what they know, so
I think this should be done first.
Of course a lot of other things sure would have to be done by the Doc Tools
team in near future, but I believe the above would be enough for a good
start.
Task force 3 - Doc Publishing
This task force would be responsible for determining and providing (with Doc
Tools team) the better distribution file formats and publishing media to the
documentation.
Maybe more imprtant than that, Doc Publishing task force would care for the
language revision (grammar, ortography, etc) of the document texts, as weel
as the aesthetics 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. Once there is a documentation
written, the Doc Publishing Manager will can also start to recruit
translators of the documents to other languages beyond English, when I'd be
glad to candidate to the Brazillian Portuguese Doc Version team.
Doc Task Coordination
The initial job of the Doc Task Coordinator would be to determine with the
team managers the chronogram that will state the date when the Harbour
Official Documentation Task Force will begin to operate and the steps
following this start date.
Of course this just could happen after the coordinator and the managers
volunteer, be chosen and assume their roles.
Sorry if I this is an inconvenient proposal. I'm aware Harbour-Project is
not a company and that nobody is paid for any participation or has the
obligation to do anything.
Let me know if there is something else I can do to help.
Best regards,
Leandro Damasio
--------------------------------------------------
From: "Bacco" <[email protected]>
Sent: Friday, February 19, 2010 9:56 AM
To: "Harbour Project Main Developer List." <[email protected]>
Subject: Re: [Harbour] Re: About Harbour Documentation
On Fri, Feb 19, 2010 at 08:27, Vailton Renato <[email protected]> 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)
[email protected]
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)
[email protected]
http://lists.harbour-project.org/mailman/listinfo/harbour
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
[email protected]
http://lists.harbour-project.org/mailman/listinfo/harbour
