Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION
On Tue, 20 Mar 2001, Scott Harrison wrote: Fine with me. Nice set of pages you have there. So I guess the next big question is, WHO WANTS TO HELP DOCUMENT THINGS? I'd love to help if you're referring to devel docs. May I suggest the use of gtk-doc? I've recently learned how to use it and I love it. I should warn though that I don't know the internals of Dia code, but would love to, and so will be asking lots of questions. If volunteers send me ([EMAIL PROTECTED]) their e-mail addresses, we can begin to set up a new effort at documentation. As soon (within a week) as there is some reasonable understanding as to how to proceed, we can begin communicating through dia-list as to what is going on. I do offer my site as a mirror site for dia to support redundancy. -Scott Hubert Figuiere wrote: Scott Harrison crit: I have a stable machine on a gigabyte network. I enjoy documentation AND am good at it, typically using XML (via Python). I love Dia. I am developing a number of things with Dia. Any chance I could host the documentation? Is there access to the original software documentation? Should we start from scratch? Perhaps Doxygen (http://www.doxygen.org/) could be used as it allow to write code and doc at the same time ? Hub -- Gustavo J. A. M. Carneiro [http://linuxdeec.fe.up.pt/~ee96090]
Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION
On Tue, 20 Mar 2001, Scott Harrison wrote: Fine with me. Nice set of pages you have there. So I guess the next big question is, WHO WANTS TO HELP DOCUMENT THINGS? I'm more interested in the xml side - ie creating tools to work with the xml or plugins to work with dia. I'd be able to provide a little about the xml from my own reverse engineering hopefully one of the dev team can provide more info (DTD isn't documentation enough). A.
Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION
Scott Harrison wrote: Fine with me. Nice set of pages you have there. So I guess the next big question is, WHO WANTS TO HELP DOCUMENT THINGS? If volunteers send me ([EMAIL PROTECTED]) their e-mail addresses, Well, I kinda already volunteered, so I'd like to contribute... although for the next month or so my first priority will be what is needed solely for my [payed] project. we can begin to set up a new effort at documentation. As soon (within a week) as there is some reasonable understanding as to how to proceed, we can begin communicating through dia-list as to what is going on. However, please note that the purpose of my original question was to locate documentation ideas that were already "there somewhere"... and to avoid the more tedious (and time-consuming) task of reverse-engineering. (Yes, I know that we programmer's tend to be sloppy about documenting for others what we make... gotta have some trade secrets... ;-) Hubert Figuiere wrote: [...snip...] Perhaps Doxygen (http://www.doxygen.org/) could be used as it allow to write code and doc at the same time ? That's an idea. But besides that, Doxygen might (?) have a problem identifying the classes buried in the Dia design, since after all it's C not C++ or Java... In my view, one of the problems with such automated tools to "resurrect and/or reverse engineer" existing code is that they're too accurate -- they include all the details and any patological interdependencies that might have grown into the source over the years, thereby obscuring the basic ideas structure. (It cannot distinguish between important and unimportant design features, ending up showing just a lot of "noise".) IMHO, merely converting code comments into HTML/RTF/whatever doesn't improve _that_ much over just reading the source files directly... It doesn't always reveal the structure. But that's just me, though... :-) Actually, I made a very tiny start using Dia itself (why not!?!!) and the UML elements, creating a class diagram based on header files and the README file. ...until I found that this was very time-consuming since I had not gained any familiarity with the source beforehand. -+-Ben-+-
Re: Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION
I'm interested in documentation, but know nothing about the internals (yet). Longer term I want to be able to use Dia functionality inother programs, esp. called from python, and that requires better understanding of the internals and the modularization. On Tue, 20 Mar 2001, Ben A. Hetland wrote: Date: Tue, 20 Mar 2001 20:51:01 +0100 To: [EMAIL PROTECTED], [EMAIL PROTECTED] From: "Ben A. Hetland" [EMAIL PROTECTED] Reply-To: [EMAIL PROTECTED] Subject: Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION Scott Harrison wrote: Fine with me. Nice set of pages you have there. So I guess the next big question is, WHO WANTS TO HELP DOCUMENT THINGS? If volunteers send me ([EMAIL PROTECTED]) their e-mail addresses, Well, I kinda already volunteered, so I'd like to contribute... although for the next month or so my first priority will be what is needed solely for my [payed] project. we can begin to set up a new effort at documentation. As soon (within a week) as there is some reasonable understanding as to how to proceed, we can begin communicating through dia-list as to what is going on. However, please note that the purpose of my original question was to locate documentation ideas that were already "there somewhere"... and to avoid the more tedious (and time-consuming) task of reverse-engineering. (Yes, I know that we programmer's tend to be sloppy about documenting for others what we make... gotta have some trade secrets... ;-) Hubert Figuiere wrote: [...snip...] Perhaps Doxygen (http://www.doxygen.org/) could be used as it allow to write code and doc at the same time ? That's an idea. But besides that, Doxygen might (?) have a problem identifying the classes buried in the Dia design, since after all it's C not C++ or Java... In my view, one of the problems with such automated tools to "resurrect and/or reverse engineer" existing code is that they're too accurate -- they include all the details and any patological interdependencies that might have grown into the source over the years, thereby obscuring the basic ideas structure. (It cannot distinguish between important and unimportant design features, ending up showing just a lot of "noise".) IMHO, merely converting code comments into HTML/RTF/whatever doesn't improve _that_ much over just reading the source files directly... It doesn't always reveal the structure. But that's just me, though... :-) Actually, I made a very tiny start using Dia itself (why not!?!!) and the UML elements, creating a class diagram based on header files and the README file. ...until I found that this was very time-consuming since I had not gained any familiarity with the source beforehand. -+-Ben-+- -- Harry George [EMAIL PROTECTED]
Re: OPEN REQUEST FOR RESURRECTING DOCUMENTATION
On Tue, 20 Mar 2001, Scott Harrison wrote: Fine with me. Nice set of pages you have there. So I guess the next big question is, WHO WANTS TO HELP DOCUMENT THINGS? If volunteers send me ([EMAIL PROTECTED]) their e-mail addresses, we can begin to set up a new effort at documentation. As soon (within a week) as there is some reasonable understanding as to how to proceed, we can begin communicating through dia-list as to what is going on. I do offer my site as a mirror site for dia to support redundancy. Are you talking about user documentation or developer documentation? Note that we now have user documentation (one of the great new features of dia 0.87, provided by the GNOME documentation project). This is being distributed with the application. If you want to contribute to this documentation, contact the GDP. There is not much developer documentation at present however. What sort of info do you want? James.
