Hi all, I have followed this thread with great interest and would like to add my 2cents as the external help author who has written the xHarbour docs:
1) Programmers are no help authors 2) Software cannot be spread without good documentation 3) xHarbour.com has invested into good documentation 4) Harbour programmers have failed to produce good documentation 5) It is impossible to create good documentation from source code To 1) Programmers want to write source code. They don't want to explain in grammatically exact words what they have done. They are satisfied when a source code works, and are in most cases unable to explain the preconditions for the source code to work. The preconditions, however, must be documented (e.g. data types of parameters that must be passed to a function). To 2) Users that try an unknown software rely on the documentation of it. Attracting users to a _programming_language_ like xBase via Harbour or xHarbour is not possible without documentation. To 3) The xHarbour investment into documentation is a logical step of xHarbour.com in providing services to the Harbour/xHarbour community. It is sad to learn that both communities are not big enough (yet?) to justify this investment. There is no payback of the investment achieved. To 4) The open source model of Harbour did not produce enough momentum for help authors to step in. Reason: the first 500 pages of documentation could be copied from the Clipper docs (illegally?) To 5) The creation of documentation must be separated from the creation of source code. There is no way around this. Reasons: a) source code comes first b) programmers are no help authors and c) documentation comes next. Conclusion: I don't know nothing about contracts between Harbour/xHarbour, but IMO it is absurd to create two times a documentation for almost the same thing. Maybe the Harbour users should learn that services cost money, even in the open source era. The service of producing documentation is not created by Harbour developers but by xHarbour.com, which has bought my services for this very issue. Regards, -- Hannes Ziegler _______________________________________________ Harbour mailing list Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
