Re: Help files
Rebecca Jean Pedersen wrote: I figured since everyone is talking help files I would just introduce myself. I'm on IRC as bex and I'm willing to help however I can. I'm somewhat new to gimp, so I won't be much good for writing new help files, but my education is in English, especially writing, so I have volunteered to proofread and edit documents. Don't sell yourself short. People very, very, familiar with a topic often "forget what they know" and, consequently, fail to properly stage concepts for the best comprehension of newcomers. On a number of occasions I have read exposition from newcomers to a topic of much higher caliber than that coming from acknowledged experts. The learning experience is still fresh to newcomers and they still remember the sequences of concepts that lead to their own "Eurekas!" and can relate these to fellow newcomers. Old hands often disassemble the scaffolding of their understanding once the framework is complete, so they have no idea how to explain what they've come to know. Jarda Benkovsky wrote: If I may add some points in favor of DocBook: - consistency - it will help make the pages the same style - easy change of style in all pages at once - I believe it's simpler than full-blown HTML (CSS ) Edheldil I'm inclined to agree. I find flat HTML documentation is hard to maintain. As much as possible writers should concentrate on content and leave issues of appearance of formatting, packaging, and delivery to downstream release mechanisms. My two U. S. cents Be good, be well Garry Osgood
Help Files
I'm trying to help Halcyon out a bit with the help files so I put up a section of my company's homepage for the project. address is http://www.solnet-data.dk/gimphelp/ If you are working on the project, please go get the template.html available on that site for use in making your docs. Thanks muchly. rjp
Re: Docbook (Help files)
On Monday, 31 Jul 2000, Kevin Turner wrote: [Kevin checks the latest mail. Now it seems we have a help template file in HTML. Okay. Uh-oh, it's under a non .gimp.org domain, Sven will frown about that.] The template includes "-" as a menu path separator. The problem with this is that it suggests actually using "-" literally in the HTML, rather than the more correct "-gt;". Personally, I think anything that makes updating the help text as easy as possible is good. Ideally, there would be a button at the bottom of the help browser labelled "email corrected version" or something, that people could use if they come across typos, wrong, or missing info. Make it totally trivial for people to scratch their itch, basically :) Austin
Re: Docbook (Help files)
On Mon, Jul 31, 2000 at 07:40:12PM +0100, Austin Donnelly [EMAIL PROTECTED] wrote: The problem with this is that it suggests actually using "-" literally in the HTML, rather than the more correct "-gt;". There is nothing wrong with using "-" in html, except for some *very* outdated and *very* broken user agents. -- -==- | ==-- _ | ---==---(_)__ __ __ Marc Lehmann +-- --==---/ / _ \/ // /\ \/ / [EMAIL PROTECTED] |e| -=/_/_//_/\_,_/ /_/\_\ XX11-RIPE --+ The choice of a GNU generation | |
Re: Docbook (Help files)
DocBook sounds fine to me presuming that the tools are validating (ie users who just type nonsense into their text editor will be rewarded with a screenful of errors) and so we get some decent structured documents, not the hacked-together nonsense you usually get when people write HTML. I don't know DocBook, but presuming all I need is some web tutorial and a bunch of RPMs I am willing to learn it and submit documentation for all file formats maintained by me or unmaintained + a bonus section for all the Gimp newsgroup users who ask.. "There are so many file formats, which should I use?" ... to which the answer is of course always use PNG :) Writing this stuff will take some time, how much time do we have? Nick.
Re: Help files
Kevin Turner [EMAIL PROTECTED] writes: Format issue 1: DocBook or HTML? DocBook. It is the Right Thing(tm) and GNOME has already assembled a nice set of tools to handle it. I'm sure the the GIMP documentation team can use some ideas and conventions from the GNOME documentation project. Please feel free to browse the nice GDP web pages. Format issue 2: Style guidelines. = Everyone probably agrees that we shouldn't have a different background colour for every help page. It might also be nice if there was some organizational consistancy from page to page. Also, is there anything that shouldn't be in the help file, or should always be in seperate files? For instance, should information about using the plug-in non-interactively not be displayed in the same file as the rest, to avoid exposing the user to "scary pdb stuff"? The way GNOME documentation is organized is more or less something like this: set titleFooApp Documentation/title book titleFooApp User's Guide/title ... /book book titleFooApp Developer's Guide/title part titleWriting Applications/Plug-ins for FooApp/title ... /part part titleFooApp API Reference/title ... /part /book /set The Evolution groupware suite uses this structure. It leads to nice results, I think. As for the look of the final output, it is just a stylesheet issue. The GDP has nice stylesheets both for printing and for generating HTML. Egger argues, "GIMP doesn't *need* help files to run, so they can be distributed seperately." Software is not complete until it has documentation. The documentation must be shipped along with the GIMP's code. (You'll also need to do that if you have automatically-generated docs for the API reference guide). Why? It's the "Who has cvs.gnome.org write-access?" song again. But it's only been three days since Piers (our new Help-guy) requested write access, so I don't feel that's a cause for alarm yet. How did Piers request access? You can always ask [EMAIL PROTECTED] and we'll take care of it. Again, please feel free to ask the GDP team if you have questions about how to write or ship documentation. Good luck, Federico
Re: Docbook (Help files)
im doing some editting as thiings are now, so the html isnt just "hacked together nonsense" it is being made coherant and valid. trust me. trust halcyon. and for those of you on the project... made a change to the template. same addy. http://www.solnet-data.dk/gimphelp/ as for it belonging somehwere else... i just put it there as a help to get the project moving. as for when to get it done... i vote for ASAP. im already proofing my butt off on docs that exist. i think we need more writers and translators. please volunteer everyone.
