Re: Headless build [was Re: [cdt-dev] RIP Wascana, Build System discuss

[James Blackburn <jamesblackburn@xxxxxxxxx>]

2009/5/26 Alex Blewitt <alex.blewitt@xxxxxxxxx>:
> 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.

If you get stuck like this, do email the list. It's likely someone's
been there before you and can point you in the direction of a
solution.

> 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.

I think everyone's in agreement on this. Unfortunately there's a huge
amount of existing undocumented code which can't be fixed overnight.
Developers adding documentation as they fix bugs will help,
contributors submitting patches with documentation would also help.

In some sense this is the _easiest_ way for the community to get
involved and help make CDT better.  It seems that everyone values good
documentation, so why don't people post their FAQs & solutions to the
wiki?  We're all guilty of this, and I know that everyone's busy, but
if every other person who has an issue resolved on the mailing list
added an entry to the FAQ, we would go a long way to solving learning
curve issues...

Seriously, if you've got some gem from the mailing list / news group,
add it to the FAQ!  It's all well and good complaining there's nothing
there, but if no one's willing to contribute it will stay that way.
Seriously, help the poor guy after you by contributing, you know you
want to :)!

Cheers,
James

> Alex
>
> Sent from my (new) iPhone
> On 25 May 2009, at 16:46, Mike Wilson <Mike_Wilson@xxxxxxxxxx> wrote:
>
> 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
>
>
>
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev
>
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev
>
>