Re: mixed signals on "Writing HTML documents", tutorial, etc.

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

Received on Friday, 15 June 2007 17:15:15 UTC