Hi,
Recently a person reported to out bug tracker that the website doesn't provide good introduction information for new developers.
So I've just taken a look at http://inkscape.org/doc/devdocs.php and I have several questions:
1. Do you find this information overall sufficient? 2. Last changes to http://inkscape.org/wiki/index.php/DeveloperManual date back to February 2007. Would anyone mind having a look and saying whether something needs changes? (btw, our wiki outputs errors again) 3. Does the flowchart at http://inkscape.org/doc/devdocs.php really reflect current state of source code? 4. Same question about class hierarchy image.
Thanks! :)
Alexandre
-----Original Message----- From: Alexandre Prokoudine [mailto:alexandre.prokoudine@...400...] Sent: vrijdag 2 januari 2009 3:21 To: Inkscape Devel List Subject: [Inkscape-devel] intro for developers
Hi,
Recently a person reported to out bug tracker that the website doesn't provide good introduction information for new developers.
So I've just taken a look at http://inkscape.org/doc/devdocs.php and I have several questions:
- Do you find this information overall sufficient?
- Last changes to http://inkscape.org/wiki/index.php/DeveloperManual
date back to February 2007. Would anyone mind having a look and saying whether something needs changes? (btw, our wiki outputs errors again) 3. Does the flowchart at http://inkscape.org/doc/devdocs.php really reflect current state of source code? 4. Same question about class hierarchy image.
It's nice that you care about the report Alex. But I am somewhat pessimistic about improvements to the documentation.
I think the single most important documentation for a floss project is how to get it built from scratch. And it must be easy to build, so the documentation is short and understandable. I ran away in desperation trying to build OpenOffice; Inkscape is very easy on windows luckily. Only thing left to do is remove the old and obsolete documentation and point to the correct wiki page. And then: get the people in our jabber or IRC channel, there's almost always people around to help with questions!
All the class diagrams, code organization, etc, I think it is hardly ever used or read. It is just too much to try and read about how a big program like Inkscape works, without having looked at the code for a long time. And, once you know how a certain piece works, the documentation on the website has become almost useless, so motivation is lacking to document it. Sifting through code is much more precise and quicker. I use notepad++'s find-in-all-files certainly once every minute during development. I usually understand written code very quickly, so maybe it doesn't work as well for people that are newer to the language.
In any case, I know little of Inkscape, and am still able to contribute. Some parts I know well, some parts I don't know anything about. It's not needed to know all :-), certainly not for all the "low hanging fruit" that we have.
To new devs: join our chat channel!
Cheers, Johan
On 01/02/2009 06:23 AM, J.B.C.Engelen@...1578... wrote:
All the class diagrams, code organization, etc, I think it is hardly ever used or read.
Well, I think most of us have read that at least once. At least I did. It can at least serve as a primer, and if it's kept up-to-date then it can even be a reference
It is just too much to try and read about how a big program like Inkscape works, without having looked at the code for a long time.
The code base itself is obviously the ultimate reference, but it's essential for new devs to have a wiki that explains the what a SPView / SPNamedView / SPDesktop / SPDocument etc. are. That will give you the big picture much faster.
And, once you know how a certain piece works, the documentation on the website has become almost useless, so motivation is lacking to document it.
Refactoring isn't always fun either, is it? Motivation can surely be found for such a thing, otherwise we would have never gotten our excellent Inkscape book and guide.
To answer Alexander's questions: 1) yes, I think it's sufficient. We need a primer, not a complete reference (although that would be great to have too) 2-4) we need some feedback from our most experience devs here, most part of it I cannot judge
Diederik
2009/1/2 Diederik van Lierop <mail@...1689...>:
On 01/02/2009 06:23 AM, J.B.C.Engelen@...1578... wrote:
All the class diagrams, code organization, etc, I think it is hardly ever used or read.
Well, I think most of us have read that at least once. At least I did. It can at least serve as a primer, and if it's kept up-to-date then it can even be a reference
I agree, although I spent a full summer working on Inkscape before I discovered this info in the wiki. Just like Johan I usually investigate code by looking at it, and often enough I find myself grepping through the whole code to understand how pieces of code are interconnected (no need for Notepad++, though :-P ). Still, every now and then I don't understand what the SPFooBar class is supposed to mean or how it relates to the things I see on my canvas and then I'm grateful if there is some piece of documentation on it. So I believe we definitely should have this material as as reference, but I feel it could be improved to help newbie developers better understand the class hierarchy. Unfortunately, I don't feel qualified/capable of doing this atm. :-(
Max
The code base itself is obviously the ultimate reference, but it's essential for new devs to have a wiki that explains the what a SPView / SPNamedView / SPDesktop / SPDocument etc. are. That will give you the big picture much faster.
I learnt some time ago that a good strategy for me to writting documentation or other usually boring stuff is to do it by chatting with other people (usually instant messaging about the subject). Then I refactor the chat log into a piece of text. That way, the ideas flow better and less painfully than when I try to write stuff laone with the sensation of being talking to the text editor.
Since I still don't know what SPViews and SPNamedViews are and I only have a vague idea about what the other SP's you mentioned are, then I would encourage you (Diederik) to explain that to me (maybe here, maybe someday on IRC). Then we refactor it. Then we publish it.
Juca
participants (5)
-
unknown＠example.com -
Alexandre Prokoudine -
Diederik van Lierop -
Felipe Sanches -
Maximilian Albert