[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [cdt-dev] CDT docs and need Info on Indexer pref panel
|
My 2 cents. Bad documentation can be more frustrating than no
documentation. Explaining technical subjects in a clear, cohesive and
accurate manner requires skills and patience not everyone has, but
sometimes people don't realize they lack those skills (the early
weeks of an American Idol season come to mind). Having a free-for-all
approach to the documentation is fine as long as there is someone
closely monitoring and massaging the contributed content. Unless we
have a resource who is committed to such policing, I'd be concerned
about opening up the docs to the bugzilla community.
John
At 11:53 AM 4/14/2010, James Blackburn wrote:
On 14 April 2010 17:30, Doug Schaefer <cdtdoug@xxxxxxxxx> wrote:
> Yeah, it already is open to the community. People can contribute patches to
> it like anything else. If you want to crowd source it in a git repo
> somewhere, that's fine as long as we can bring it back into the doc plug-in
> for release.
Well AFAICS it's not open as the barrier to entry is too high:
- contributors need to find and checkout documenation
- contributors need to write HTML
- contributors need to submit patches for approval and commit by committers.
What the other projects have been doing is putting the documentation
on the wiki which can then be edited by anyone with a bugzilla
account.
For releng purposes they've generate the distributed docs from the wiki.
Wiki isn't perfect, but it certainly lowers the barrier to entry.
Cheers,
James
>
> On Wed, Apr 14, 2010 at 12:20 PM, Alena Laskavaia
<elaskavaia.cdt@xxxxxxxxx>
> wrote:
>>
>> What does mean "open documentation to community"? Allow write access
>> to cvs? Or read access?
>>
>> On Wed, Apr 14, 2010 at 12:18 PM, Marc Khouzam
>> <marc.khouzam@xxxxxxxxxxxx> wrote:
>> >> What do people think about opening up the documentation to the
>> >> community?
>> > +1
>> > On top of improving the docs, this would give an easy way for someone to
>> > start
>> > contributing to CDT, which may be the start of other types of
>> > contributions.
>> >
>> > Great idea James.
>> >
>> > ________________________________
>> > From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx]
>> > On
>> > Behalf Of Andrew Gvozdev
>> > Sent: Wednesday, April 14, 2010 10:27 AM
>> > To: CDT General developers list.
>> > Subject: Re: [cdt-dev] CDT docs and need Info on Indexer pref panel
>> >
>> > Hi James,
>> >
>> >> What do people think about opening up the documentation to the
>> >> community?
>> > I think it is a great idea. +1 for that.
>> >
>> > Andrew
>> >
>> > On Tue, Apr 13, 2010 at 3:36 PM, James Blackburn
>> > <jamesblackburn@xxxxxxxxx>
>> > wrote:
>> >>
>> >> Hi Frank,
>> >>
>> >> That sounds like a really noble cause!
>> >>
>> >> There are a few things I've found problematic when working with the
>> >> documentation (both while tweaking, and as a user) that I thought it
>> >> would be good to enumerate:
>> >> - Much of it was created using FrontPage and isn't easy for
>> >> developers (if they have the inclination) to improve with a text
>> >> editor
>> >> - Many existing features are documented 3 times: under tasks,
>> >> concepts and reference. As a user you need to look in all 3 places.
>> >> - The documentation is locked away in CVS.
>> >>
>> >> The last point is the most major in my mind. It's near impossible for
>> >> people to contribute improvements to the documentation. The recent
>> >> user-contributions I've seen fly-by have been for typos rather than
>> >> anything substantial...
>> >>
>> >> A number of projects have jumped on the documenation crowd-sourcing
>> >> band-wagon. There are a few blog posts about it:
>> >> http://aniszczyk.org/2010/03/13/crowdsourcing-documentation-at-eclipse/
>> >>
>> >>
>> >>
http://greensopinion.blogspot.com/2010/03/crowdsourcing-documentation-made-easy.html
>> >>
>> >> We're really lucky to have some dedicated question-answerers on the
>> >> Eclipse forums. It would be great to tap some of the community and get
>> >> them to help out with improving our documentation situation. IMHO
>> >> developers often don't make the best documenters, and only the
>> >> community at large can point out the deficiencies that we'd never see.
>> >> Having spent the afternoon facing users (internal ones at that) it's
>> >> really amazing what knowledge/concepts we take for granted...
>> >>
>> >> What do people think about opening up the documentation to the
>> >> community?
>> >>
>> >> Cheers,
>> >> James
>> >>
>> >>
>> >> On 13 April 2010 20:00, <Frank.Turovich@xxxxxxxxx> wrote:
>> >> > Okay, now that taxes are done I'm turning my attention to the CDT
>> >> > docs.
>> >> > Over the next few weeks I'm going to attempt to:
>> >> >
>> >> > - review all my previous patches and see if they still apply. If they
>> >> > do, I'll commit the patch and mark the bug as fixed. If the initial
>> >> > patch
>> >> > can no longer be applied, I'll update with a new version and apply
>> >> > that,
>> >> > then again close the bug.
>> >> >
>> >> > - review all other CDT doc bugs and patch as many as I can
>> >> >
>> >> > - rearrange the CDT manual's TOC > Pref panels section to more
>> >> > closely
>> >> > match what the user finds in the current release.
>> >> >
>> >> > - start filling in obvious doc holes.
>> >> >
>> >> > And that's where I need your help. One of the big pref panels not
>> >> > covered is the Indexer. Where can I find more information of its
>> >> > design
>> >> > goals and options so I can document them for our users?
>> >> >
>> >> > All input appreciated.
>> >> >
>> >> > thx // frank
>> >> >
>> >> > _______________________________________________
>> >> > 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
>> >
>> >
>> _______________________________________________
>> 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
