On 14 Jun 2007, at 21:59, Dan Connolly wrote:
> On Thu, 2007-06-14 at 20:39 +0100, Geoffrey Sneddon wrote:
>> On 14 Jun 2007, at 19:42, Dan Connolly wrote:
>>
>>> I'm getting mixed signals. The tasks survey
>>> shows 42 people interested in tutorial development,
>>> but I'm struggling to get any tangible progress in that
>>> direction.
>>
>> I feel there's little point in starting until after the spec has been
>> reviewed, which is why I've not done anything yet.
>
> Little point? I don't see it that way.
>
> Writing end-user documentation is often
> a good way to find design problems. If a design is hard to explain,
> maybe it's broken or at least merits closer scrutiny.
>
> In my experience, it's best not to separate do design, testing, and
> documentation; better to iterate concurrently.
Agreed. But iterating shouldn't mean having to throw away huge
amounts after the initial review.
>
>>> And now when I look at the volunteers to review sections
>>> of the HTML 5 spec, there's noticeable lack of reviewers
>>> for the "Writing HTML documents" documents section.
>>
>> Maybe this shows people feel this shouldn't be in the spec, even
>> informatively (but that should really be another thread)?
>
> The WG has decided[9May] that the text merits review. If noone
> proposes to remove it, I suppose the editor will leave it in.
> Moreover, a proposal to remove that section would be much more
> welcome from someone who has read it in some detail than from someone
> who has not.
I'm well aware of what the WG decided (though, to go against my
previous point, the text as it stands (to my memory at least) is
really aimed at a different level to what a tutorial would be aimed at).
> Some might prefer to read what's there. Some might prefer to
> write something new instead. Some prefer a mix of both,
> I suppose.
I think the first issue is this: what level/group are the follow
aimed at:
a) The "Writing HTML Documents" section of the spec,
b) The WG tutorials.
My suggestion would be to aim the former at people implementing the
spec as a authoring tool or markup generator, and the latter at
people hand-coding, probably starting by going over the extreme basics.
> You can update your response to the task survey at any time.
> http://www.w3.org/2002/09/wbs/40318/tasks83/
I'll add it to what I currently have, but it is one part of the spec
that I am more familiar with.
> If you checked the "tutorial development, quick
> reference, course materials, ..." task, please give
> some thought to what you meant by that and either
> or elaborate in a survey comment or send us mail or uncheck
> that task or start reviewing something or start writing something.
I think the rest of the email answers most of this â€” I'll try and
start when I have time (I'm away both this weekend and next, but once
I start to have time I should be able to spend plenty of time dealing
with it).
- Geoffrey Sneddon