Hi Pete, > Ok, let's (try to) write some documentation. > But before we start we have to know, what format should adopt. I mean, is > Nanforum format mandatory or we could follow a more human form?
No, Nanforum format is mandatory. > /* $DOC$ > * $TEMPLATE$ > * Function > * $NAME$ > * HB_DirExists() > * $CATEGORY$ ... > * $END$ > */ > > Now i have one/two more questions: > Are all those eye-bothering '$' & '*' necesary? > Also, are _all_ the above statements mandatory or we could leave out some > of them like $SUBCATEGORY$ $STATUS$ $COMPLIANCE$ etc. to make the txt more > compact and 'quick-readable' > Supposing the answers are 'yes' let see how the above document > could be written: It could be written in any way, but then you'd need to create parsers for each format ppl happened to use. We've choosen NANFORUM format, because it is already developed, fits our purpose, easy to use, and we have already created tools that can process it. Our goal in this project is _not_ to invent or reinvent a new documentation format. Our goal is to document Harbour functions using an existing _standard_. This standard is NANFORUM. > ------------------------------------------------------------------------------ > > An other critical question is how do i decide to document what? > That is, how do I know if the above documentation is not already written by > someone else? Obviously, somebody has to monitor the whole process, keeping an > eye on 'who is documenting what' to avoid overlapping writing. It's simple: If something is not present in /doc/en-EN/ folder, it's safe to document. (Even if it's present, it can probably need a review/rewrite.) "who writes what": It requires some very basic synchronization between documentation writers. I don't think we should develop some over-burocratic scheme for this yet. If someone is starting seriously on a given lib or set of source files, it's enough to drop here an e-mail. At the time when this becomes inadequate, we can use a simple text file on wiki or in SVN, called "TODODOC.txt" or similar. This file can have each Harbour function, grouped by source file, with a status: TODO [username] -> DONE [username] -> CHECKED [username] Brgds, Viktor _______________________________________________ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
