For me too, trying to figure out how to add a -framework flag to the linker was an exercise in frustration itself and at one point, I was writing my own wizard with a new project by unzipping a template project with all the metafiles set up correctly because the documentation was next to useless. Many of the APIs are marked EXPERIMENTAL and appear to have been that way for a while; and much documentation on e.g. build was written against 3.0 with a "migration guide" to 4.0. So I have to learn an antique tech to then learn the diffs of that tech to just get to one version behind?
It's like into tests. Once one starts to fall, you don't notice when the second starts to fall, and before you know it, you're facing a project whose unit tests are dead weight. Then, of course, you feel like there's no point in writing new tests because there would be no alert if it started to fail.
Does documentation help those who already know how it works? No, they've grown up with the stuff - and probably wrote half of it. For JDT type projects, half of the people probably work in the next office to you, and you can ask them over lunch. But what happens when that project is mothballed or put into maintenance mode? People get reassigned and the knowledge is lost.
Code can certainly evolve faster than documentation. That doesn't necessarily mean it should. But for projects with longevity, particularly those where it's important to encourage growth over time within a communtiy, documentation is the torch that gets passed from one generation to the next.
Code without unit tests is deemed less valuable than code with. The same should be true of features without documentation.
Alex
Sent from my (new) iPhone
I don't have any answers, but I have to agree with the sentiment. On the platform, we usually make the absolute minimum investment in updating the documentation that we can get away with. It's not because it's boring, it's just that there's always more work to do, and documentation isn't a high enough priority.
McQ.
<graycol.gif>Jesper Eskilson ---25/05/2009 10:50:34---James Blackburn wrote:
<ecblank.gif>
From: | <ecblank.gif>
Jesper Eskilson <jesper.eskilson@xxxxxx> |
<ecblank.gif>
To: | <ecblank.gif>
"CDT General developers list." <cdt-dev@xxxxxxxxxxx> |
<ecblank.gif>
Date: | <ecblank.gif>
25/05/2009 10:50 |
<ecblank.gif>
Subject: | <ecblank.gif>
Re: Headless build [was Re: [cdt-dev] RIP Wascana, Build System discussion] |
James Blackburn wrote:
>> Well, Bugzilla is a really lousy way of storing documentation. You pretty
>> much guarantee that no one will find it unless they know exactly where it
>> is.
>
> I agree. Documentation patches are appreciated :)
One problem is that there seems to be a general consensus here that
Bugzilla is a good place to store design documentation, which I think is
a really lousy idea. Maybe while the documentation is being produced,
but using Bugzilla as a sort of DMS.
The general feeling I have is that documentation is considered (both in
CDT but even in the open-source community in general) something boring
which can be delayed until after release and left for others to
contribute. In fact, the lack of documentation in some places is a real
hindrance to CDT adoption.
I understand that fixing the current state of CDT being badly documented
requires a substantial effort to fix, and that CDT is seriously
understaffed. The problem is that things will only get worse unless all
newly developed code and new features have some form of documentation
requirement. Do they? Otherwise, the amount of undocumented features and
code will only continue to grow.
--
/Jesper
_______________________________________________
cdt-dev mailing list
cdt-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cdt-dev
|
