[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: Headless build [was Re: [cdt-dev] RIP Wascana, Build System discussion]
|
Alex Blewitt wrote:
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.
This is also known as the "Broken Windows"-theory:
http://en.wikipedia.org/wiki/Fixing_Broken_Windows
Does documentation help those who already know how it works? No, they've
grown up with the stuff - and probably wrote half of it.
Another problem with is even harder to handle is the fact that it is
difficult for developers who knows how everything works to write
documentation for people who don't. This usually causes the
documentation to contain "white spots": things which the developer
doesn't even realize needs documenting.
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.
It should be, yes.
--
/Jesper
