Subject: [netmod] summary line in descriptions

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 06 Dec 2017 13:37:36 +0100

Hi,

although detailed descriptions is a good thing, my recent experiences with web
clients for RESTCONF indicate that they can become clumsy and unwieldy in such
user interfaces. I think it would be useful to adopt a convention similar to Git
commit messages: one relatively short summary line followed by an empty line,
and the rest of the description after that. User interfaces could then easily
recognize and use the summary line.

Perhaps 6087bis could include such a recommendation.

Lada

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 6 Dec 2017 14:14:05 +0100

I am not sure design decisions of some web clients that provide clumsy
user experience should impact how we write data models. If we need
summary lines, we should properly separate them via

  ext:summary "this does magic, see the description"

instead of relying on conventions.

/js

On Wed, Dec 06, 2017 at 01:37:36PM +0100, Ladislav Lhotka wrote:
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 06 Dec 2017 14:51:10 +0100 (CET)

> instead of relying on conventions.

I agree.  Incidentally, that's what we do (with a vendor specific
extension).

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 06 Dec 2017 14:55:49 +0100

> I agree.  Incidentally, that's what we do (with a vendor specific

So if you have a single-line description, you replicate it in this extension's
parameter?

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 06 Dec 2017 15:00:41 +0100 (CET)

> So if you have a single-line description, you replicate it in this extension's

I have seen that.  In some cases people simply don't put in the normal
description in that case, just tailf:info.  But for "real" nodes, the
description tend to be longer than the short info.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 06 Dec 2017 15:25:37 +0100

> description tend to be longer than the short info.

I just briefly checked "ietf-interfaces" and "ietf-routing", and most
descriptions for data nodes are either single line or already follow the
convention that I proposed.

Lada

> > > > > although detailed descriptions is a good thing, my recent experiences
> with
> > > web
> > > > > clients for RESTCONF indicate that they can become clumsy and unwieldy
> in
> > > such
> > > > > user interfaces. I think it would be useful to adopt a convention
> similar
> > > to Git
> > > > > commit messages: one relatively short summary line followed by an
> empty
> > > line,