Subject: [decade] Trends in DECADE reviews

From: "Woundy, Richard" <[email-masked]>
Date: Thu, 16 Feb 2012 17:10:46 +0000

Decade WG document editors,

There are a few trends in our document style that we need to fix ASAP. While these comments below were taken from the AD review of requirements, I have seen similar comments for all the documents we have sent to our AD.

In short, we need to stop referring to DECADE as an actor (a person or thing), we need to avoid discussing DECADE "protocols", and we need to avoid referring to the DECADE working group (or other IETF working groups as they are all temporary).

> A major problem of this document is that it uses DECADE as an actor, and specifies what DECADE must do. But DECADE is not an actor. The document really needs to be written in terms of the components of the system, and the specification of compliant behaviors. DECADE is really only a set of documents specifying compliance rules. The actors are decade-compatible servers, decade-compatible clients, decade-compatible protocols and the specification must describe what those actors are required to do, not what DECADE must do.

> is this use of decade a reference to the WG or the system? DECADE does not exist

>"DECADE does not intend". DECADE is not a concrete thing, so it cannot "do" anything. It is not sentient, so it cannot "intend". The closest you come to decade being concrete it that is a WG, but a WG is a temporary thing and the document will outlast its lifetime; you should write in terms of the specifications; the specifications are real things.

> The WG has explicitly NOT been authorized to create a new protocol (i.e. a new messaging protocol). That was very deliberate. Many of the tasks required of a "decade system" can be done using existing open, standard protocols. The WG is chartered to explore the problem space, and to develop an abstract architecture to break the problem into manageable parts, and to identify the requirements for those parts to work together. A gap analysis identifying how existing protocols cannot meet the requirements can be part of the outcome, but creating a protocol is explicitly out of scope of this WG.

-- Rich

---

From: Dave CROCKER <[email-masked]>
Date: Thu, 16 Feb 2012 11:26:28 -0800

fwiw, I'm gearing up to do the apps directorate review for some of your docs and 
would heartily concur with the kinds of issues Richard is raising.

d/

On 2/16/2012 9:10 AM, Woundy, Richard wrote:
> There are a few trends in our document style that we need to fix ASAP. While
> these comments below were taken from the AD review of requirements, I have seen
> similar comments for all the documents we have sent to our AD.
>
> In short, we need to stop referring to DECADE as an actor (a person or thing),
> we need to avoid discussing DECADE “protocols”, and we need to avoid referring
> to the DECADE working group (or other IETF working groups as they are all
> temporary).
>
>  > A major problem of this document is that it uses DECADE as an actor, and
> specifies what DECADE must do. But DECADE is not an actor. The document really
> needs to be written in terms of the components of the system, and the
> specification of compliant behaviors. DECADE is really only a set of documents
> specifying compliance rules. The actors are decade-compatible servers,
> decade-compatible clients, decade-compatible protocols and the specification
> must describe what those actors are required to do, not what DECADE must do.
>
>  >"DECADE does not intend". DECADE is not a concrete thing, so it cannot "do"
> anything. It is not sentient, so it cannot "intend". The closest you come to
> decade being concrete it that is a WG, but a WG is a temporary thing and the
> document will outlast its lifetime; you should write in terms of the
> specifications; the specifications are real things.
>
>  > The WG has explicitly NOT been authorized to create a new protocol (i.e. a
> new messaging protocol). That was very deliberate. Many of the tasks required of
> a "decade system" can be done using existing open, standard protocols. The WG is
> chartered to explore the problem space, and to develop an abstract architecture
> to break the problem into manageable parts, and to identify the requirements for
> those parts to work together. A gap analysis identifying how existing protocols
> cannot meet the requirements can be part of the outcome, but creating a protocol
> is explicitly out of scope of this WG.
>
> -- Rich
>

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Feb 2012 20:47:16 +0100

On Feb 16, 2012, at 18:10, Woundy, Richard wrote:

> trends in our document style that we need to fix ASAP

Can I generalize on that a bit, with a certain danger of being a bit offensive?

You (WG during document reviewing, document authors) really need to turn down your tolerance of muddled thinking.

I really like your work, but good work is not enough: you have to clean up the documents, too.

Thank your for tolerating this little public service announcement.

Grüße, Carsten