I don't know exactly what you're thinking on the whole of the format, so this may not work. I was envisioning a documentation set consisting of relatively small documents about particular subjects in gtk-gnutella, maybe with links to logical sub-topics (or "see also" references, in the case of man pages), which are explained in detail in a different document. In this way, if we use acronyms and the documents are all fairly short, then there is less chance of a user skimming past the first use and getting confused by a barrage of acronyms. :) If it were going to be one or just a few lengthy documents, then I could see how acronyms could become a problem. It's just my own personal experience with manuals and such, that I dislike reading lengthy terms when a commonly known acronym is available - it takes more time and any necessary redundancy is exacerbated.
Unfortunately I don't have any experience editing or creating man pages, and have very little experience with HTML, but from what I've seen, neither look very difficult. It's just that I will not be as apt to notice editing issues such as those brought up in DOC-STYLE about ending all lines with a space and so forth.
Finally, I would just say that I'm not really sure where to get started. I suppose for now I'll look up all the current documentation to see where we stand. Also, if there are any current questions you have about the code as far as what it's doing, and you don't want to bug the developers with it, I could have a look at it. Not knowing anything about the structure of the program, I can't promise anything, but I'll see what I can do. :)
Thanks!
Alan
Murphy wrote:
Hey' On Wed, 26 Nov 2003 16:29:03 +0000 Alan Gifford wrote:Hello everyone! I'm new to the development list. I was interested in finding out what kind of documentation support is currently ongoing forThere's nothing actively in progress but you're the third person this week to express interest. I had started writing user docs but I sort of ran out of steam. On the other hand, I'm starting to finally feel knowledgable enough to start writing again and a little help would be a real inspiration. I would be happy to coordinate and contribute. I took a first stab at a DOCSTYLE a while back, which is attached (and open to debate.)the project. I doubt that my C programming skills are up to par for developing for the project, and I think I would make a better documentation writer for the time.Excellent! The developers are so strapped for time that I hate to bug them but sometimes the only way to get an answer is to understand the C, which I can't do. Having someone who can would be a real boost. I think your approach is an excellent one. The gnutella protocol is quite complex and I've certainly learned a lot while trying to grapple with doc writing. Please feel free to contact me off list or look for eqom14 in #gtk-gnutella on irc.freenode.net -- Murphy
