Quoting Murphy <[EMAIL PROTECTED]> from ml.softs.gtk-gnutella.devel: :end) would be the README in the dist and the manpage since these are :what's generally installed on the system. The README is, for those of us :who read the docs, the first thing we read after we are convinced to :download by freshmeat | webpage. At that point, it's the README that :determines whether I'm going to actually compile the sucker and check it :out. I want the README (or INSTALL) to tell me what any gtkg specific :./configure options are all about - I had to browse the cvs to figure out :what that shell option was all about. I guess the logical (traditional) :structure for the README would be intro, compile, install, use, further :info and pointers.
I concur with that. The README is really mostly in the form it had when I took over the project lead in September 2001. It needs complete rewriting. :The manpage is the first place (theoretically) that people seek help and I :think those that are actually willing to read it and help themselves :should be rewarded by its usefullness. Openbsd users will be especially :thankful that they will be able tell newbies "man gtk-gnutella, jerk!" I :was going to start playing with this, myself. There is an embryon for a man page in the debian/ directory. Mostly because I don't know how to tell automake/autoconf about it for installation everywhere. :I think source for all other docs (including the web page) should be in :sgml/xml format so they can be converted to other formats. Linuxdoc or :whatever. The separation of content from presentation will really help :potential translators. Help pages that involve screenshots, etc will much :easier to upgrade when the gui changes. I think XML/SGML is the WORST possible choice. But I agree that separation of presentation and content is important. That's why I'd like to use the POD format defined in Perl. To me it's the best compromize between formatting and readability: you can read POD source as you would read text, mostly. Can't do that with *ML forms. :I guess you'll need to do documentation on the developer end before all :this, since that's what the user docs will be based on. I kind of disagree here. I think user documentation is the first one needed. Simply because there are far more users out there than there are developers. And developers can read the source code, and gather some information, whereas users can't do that. So users should be our first target. There are many features of GTKG that no one knows because there's no mention of those anywhere. Raphael ------------------------------------------------------- This SF.net email is sponsored by: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp _______________________________________________ Gtk-gnutella-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/gtk-gnutella-devel
