IETF Logo Mail Archive

Re: [netmod] summary line in descriptions

Ladislav Lhotka <lhotka@nic.cz> Wed, 06 December 2017 14:25 UTC

Return-Path: <lhotka@nic.cz>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id B1C67126DD9 for <netmod@ietfa.amsl.com>; Wed, 6 Dec 2017 06:25:41 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -7
X-Spam-Level:
X-Spam-Status: No, score=-7 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=nic.cz
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id lKE8GgwD_g0A for <netmod@ietfa.amsl.com>; Wed, 6 Dec 2017 06:25:40 -0800 (PST)
Received: from mail.nic.cz (mail.nic.cz [IPv6:2001:1488:800:400::400]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id B357D1270FC for <netmod@ietf.org>; Wed, 6 Dec 2017 06:25:39 -0800 (PST)
Received: from birdie1784 (unknown [IPv6:2001:718:1a02:1::380]) by mail.nic.cz (Postfix) with ESMTPSA id 17AF264491; Wed, 6 Dec 2017 15:25:38 +0100 (CET)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=nic.cz; s=default; t=1512570338; bh=0Qo2+MCZ5soKx2OPkbB5MobhNzFkN/teND8GcrLW8Dc=; h=From:To:Date; b=hd6aVixJGjpvuf9bZNO+5rorF+5zjYIk23r8OKfnxRCQKzIDqoBvJ3QJD9ulr1Bai 8FEsgEkpivOJeNWBd2e87RUKGe2KFKX7V+1dNc3U86Ha7TjGfESeTeLdd1j5+QUoiw 8y8g9sZGoQXEqr2C679W3fgEV4CG+EHBP8XCcTBM=
Message-ID: <1512570337.2653.68.camel@nic.cz>
From: Ladislav Lhotka <lhotka@nic.cz>
To: Martin Bjorklund <mbj@tail-f.com>
Cc: j.schoenwaelder@jacobs-university.de, netmod@ietf.org
Date: Wed, 06 Dec 2017 15:25:37 +0100
In-Reply-To: <20171206.150041.1063143145053874766.mbj@tail-f.com>
References: <20171206131405.cwi4eoikau67abps@elstar.local> <20171206.145110.2020944959715437189.mbj@tail-f.com> <1512568549.2653.62.camel@nic.cz> <20171206.150041.1063143145053874766.mbj@tail-f.com>
Organization: CZ.NIC
Content-Type: text/plain; charset="UTF-8"
X-Mailer: Evolution 3.26.2
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: clamav-milter 0.99.2 at mail
X-Virus-Status: Clean
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/XJQd9fKwIF5NemXO2TIcTDRZaMc>
Subject: Re: [netmod] summary line in descriptions
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 06 Dec 2017 14:25:42 -0000

On Wed, 2017-12-06 at 15:00 +0100, Martin Bjorklund wrote:
> Ladislav Lhotka <lhotka@nic.cz> wrote:
> > On Wed, 2017-12-06 at 14:51 +0100, Martin Bjorklund wrote:
> > > Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> wrote:
> > > > 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.
> > > 
> > > I agree.  Incidentally, that's what we do (with a vendor specific
> > > extension).
> > 
> > So if you have a single-line description, you replicate it in this
> extension's
> > parameter?
> 
> 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.

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

> 
> 
> /martin
> 
> 
> 
> > 
> > Lada
> > 
> > > 
> > > 
> > > /martin
> > > 
> > > 
> > > > 
> > > > /js
> > > > 
> > > > On Wed, Dec 06, 2017 at 01:37:36PM +0100, Ladislav Lhotka wrote:
> > > > > 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
> > > > > 
> > > > > _______________________________________________
> > > > > netmod mailing list
> > > > > netmod@ietf.org
> > > > > 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/>
> > > > 
> > > > _______________________________________________
> > > > netmod mailing list
> > > > netmod@ietf.org
> > > > https://www.ietf.org/mailman/listinfo/netmod
> > > > 
> > -- 
> > Ladislav Lhotka
> > Head, CZ.NIC Labs
> > PGP Key ID: 0xB8F92B08A9F76C67
> > 
-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

v2.30.2 | Report a Bug | By Email | System Status