Re: User Facing Documents

Bijan Parsia wrote:

> I have trouble reconciling this with our initial debate about publishing 
> WDs and what it means to publish one. Now, perhaps you've changed your 
> mind about that, which is fine, but I'm unclear where that leaves other 
> then-like-minded people.
> 

I have lost the context about my alleged change of mind ... I don't 
believe it matters.


> Furthermore, WDs are somewhat static (being snapshots) where as 
> explanatory material can fruitfully be more dynamic (esp. for 
> non-implementors, it's helpful for the canonical explanation to  but up 
> to date as possible).

This seems to be the tension between editors draft and working drafts.
Working drafts are better for review purposes because they are static.
For some other purposes the most up-to-date version is also useful.

I think editing such UFDs in the Wiki and then from time to time 
publishing snapshots as WDs for review is useful.

Stable docs are very helpful for review, partly because it is then clear 
that you are talking about the same words - since a Wiki page may 
change, it is quite possible to end up talking at cross purproses.

A concern with only the technical docs as FPWDs is that they will not 
generate sufficiently wide review.

As UFDs mature we can determine whether their best final resting place 
is in the Wiki or as WG Notes or Rec Track docs.


> 
> So, I have a compromise proposal. Instead of WDs, why don't we develop 
> explanatory material in the Wiki and then have a section in the core 
> Trio WDs labeled "Explanatory Material" that contains pointer to our 
> current best effort wiki pages? Ideally, we'll get lots of feedback on 
> what's valuable and useful and what's not which we can, eventually, 
> migrate to submissions, W3C external homes, recs, or parts of other recs 
> as seems sensible. 

I am of the opinion that we will need to get these out as published WDs 
sooner rather than later, for the purpose of review. I do not believe 
that we will get the same quality of review from Wiki pages. Mainly 
because, as you say below, they are less work for the WG, and potential 
reviewers will interpret that as the WG not caring about what these 
pages say, and hence these pages are not worth reviewing.

 > This seems lighter weight and potentially very
> productive as we don't have to hash anything out as a group about those 
> pages, necessarily.
> 

Any hashing out as a group for such pages is necessary for the group's 
work anyway. If we, as a group, are not able to articulate in relatively 
simple language what the more technical descriptions are saying then we 
are failing. As an example, if a simple description in a UFD of a QCR is 
inadequate (after say an editor, and a first reviewer have looked at it) 
then it shows that the group as a whole has failed to adequately discuss 
QCRs to the extent that we are on the same page. These sort of UFDs are 
not about describing corner cases.

Jeremy

Received on Monday, 5 November 2007 16:51:23 UTC