Re: Git Contributor' summit: Documentation,

[Junio C Hamano <gitster@pobox.com>]

Toon Claes <toon@iotcl.com> writes:

> I've expressed myself multiple times as well how excited I am to have
> Julia working on this, but it cannot be expressed enough.

;-)

>> list, ever. I just hope that old-timers who really do not need the
>> documentation nor understand the need of those who do need it show
>> enough appreciation for the fresh views and for Julia's understanding
>> of the target audience.)
>
> I think the old-timers do, but it takes skills to have a very deep
> understanding and still being able to explain things to newbies.

Not just these two skills, but you need to know what are the points
new people find hard to get when they are starting, and that is the
weakest spot for our old-timers.

>> There was support for replacing outdated material and for merging useful
>> improvements, then iterating, rather than trying to perfect everything
>> before it lands. Bringing user feedback to the list without flooding it
>> remains a challenge.
>
> Iteration will be key here, and I would say some steps have been taken
> already. Very tiny steps though.

IIRC, the view in the room was in favor of keeping and incrementally
improving the manual pages and reference material while rewriting
tutorials and material on concepts from scratch.  I very much agree
with the "rewrite from scratch" part, because the concepts have
evolved and the world view have been updated even if the concepts at
the very core of the system may have not changed.