IETF Logo Mail Archive

Re: [netmod] summary line in descriptions

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Wed, 06 December 2017 13:15 UTC

Return-Path: <j.schoenwaelder@jacobs-university.de>
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 550481286C7 for <netmod@ietfa.amsl.com>; Wed, 6 Dec 2017 05:15:43 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_NONE=-0.0001] autolearn=ham autolearn_force=no
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 Yg5jjDmtbZOM for <netmod@ietfa.amsl.com>; Wed, 6 Dec 2017 05:15:40 -0800 (PST)
Received: from atlas5.jacobs-university.de (atlas5.jacobs-university.de [212.201.44.20]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id E466E128792 for <netmod@ietf.org>; Wed, 6 Dec 2017 05:15:37 -0800 (PST)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas5.jacobs-university.de (Postfix) with ESMTP id 15CFEE91; Wed, 6 Dec 2017 14:15:36 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas5.jacobs-university.de ([10.70.0.217]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10032) with ESMTP id WZPZMnZ_YOa7; Wed, 6 Dec 2017 14:15:34 +0100 (CET)
Received: from hermes.jacobs-university.de (hermes.jacobs-university.de [212.201.44.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "hermes.jacobs-university.de", Issuer "Jacobs University CA - G01" (verified OK)) by atlas5.jacobs-university.de (Postfix) with ESMTPS; Wed, 6 Dec 2017 14:15:36 +0100 (CET)
Received: from localhost (demetrius1.jacobs-university.de [212.201.44.46]) by hermes.jacobs-university.de (Postfix) with ESMTP id 020F420129; Wed, 6 Dec 2017 14:15:36 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius1.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id f9WlFG_fPwvQ; Wed, 6 Dec 2017 14:15:35 +0100 (CET)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id D313C2012C; Wed, 6 Dec 2017 14:15:34 +0100 (CET)
Received: by elstar.local (Postfix, from userid 501) id 7B952418DECC; Wed, 6 Dec 2017 14:14:05 +0100 (CET)
Date: Wed, 06 Dec 2017 14:14:05 +0100
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: Ladislav Lhotka <lhotka@nic.cz>
Cc: NETMOD WG <netmod@ietf.org>
Message-ID: <20171206131405.cwi4eoikau67abps@elstar.local>
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
Mail-Followup-To: Ladislav Lhotka <lhotka@nic.cz>, NETMOD WG <netmod@ietf.org>
References: <1512563856.2653.41.camel@nic.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <1512563856.2653.41.camel@nic.cz>
User-Agent: NeoMutt/20170714 (1.8.3)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/kGqlVnf5x2f0a4HeYTrvrP0tCIs>
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 13:15:43 -0000

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:
> 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/>

v2.14.0 | Report a Bug | By Email