Subject: Re: [MIB-DOCTORS] updated MIB document templates

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 01 Jun 2013 07:28:34 +0200

Hi David,

On 2013-05-31 23:52 David Harrington said the following:
> Hi,
> 
> I have updated the MIB document templates (attached).
> Tools.ietf.org has them here:
> http://tools.ietf.org/tools/templates/mib-doc-template-xml.txt
> http://tools.ietf.org/tools/templates/mib-doc-template-advice.txt
> http://tools.ietf.org/tools/templates/mib-doc-template-plain.txt
> 
> Can you put these updated versions into the repository?

Done!

Best regards,

	Henrik

---

From: Andy Bierman <[email-masked]>
Date: Sat, 1 Jun 2013 10:11:13 -0700

Hi Henrik,

Can you please make http://tools.ietf.org/templates a link
called 'Templates' under the Internet Drafts index in
the IETF home page?

I am going to work with YANG Doctors to get YANG templates updated.
I do not see the YANG Security Considerations template on this page.
Can you add a link (forget the URL) on the templates page?

Thanks Dave for being pro-active.  This sort of thing really helps
improve consistency and reduce review nits.

Andy

On Fri, May 31, 2013 at 10:28 PM, Henrik Levkowetz <[email-masked]>wrote:

> _______________________________________________
> MIB-DOCTORS mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/mib-doctors
>

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 01 Jun 2013 20:06:49 +0200

Hi Andy,

> called 'Templates' under the Internet Drafts index in

You probably mean to point to http://tools.ietf.org/tools/templates, yes?

Now, linking to that will show both new and old versions of a number
of templates, so I'm not sure that's really optimal.  Also, if you're
talking about http://www.ietf.org/, I'm not the one to ask, as that
page is maintained by the secretariat.

If you want a link to a complete collection of templates (which is what
I think you want) then we probably need to do a bit of work to make
http://tools.ietf.org/tools/templates a properly maintained page, not
just a directory list.

The templates I currently have there are:

  * David's mib-doc-templates
  * Elwyn's generic draft template

Are there other templates already available which we could/should put
in the same place?

> Can you add a link (forget the URL) on the templates page?

I can add a copy, or if we do a maintained index page there, I could
add a link, certainly.  But I need to know where to point to ,;-)

Best regards,

	Henrik

---

From: "David Harrington" <[email-masked]>
Date: Sun, 2 Jun 2013 01:02:20 -0400

Hi,

David Harrington
[email-masked]
+1-603-828-1401
-----Original Message-----
From: Henrik Levkowetz [mailto:[email-masked]] 

If you want a link to a complete collection of templates (which is what I
think you want) then we probably need to do a bit of work to make
http://tools.ietf.org/tools/templates a properly maintained page, not just a
directory list.

Are there other templates already available which we could/should put in the
same place?
[dbh>] 
When I wrote the mib  templates, there was debate about how useful they
would really be.
Given that I have not had more than a few queries about the templates, I
don't detect much usage (or knowledge) of the templates.
But Andy's idea of putting a link to templates in the datatracker could help
make them more visible and accessible.
And having templates for YANG, to supplement the mib and general templates,
might make authors more likely to utilize templates.

Lots of the template material, like security considerations, are
area-specific, and only relevant to part of a document.
There has been area-specific interest in requiring sections in documents,
like Security Considerations and IANA Considerations.
The IETF has said "no, we don't sections that MUST be included in
documents."
At the same time, authors complain they don't have adequate directions for
how to write a security section, or an OPS/NM section or a Transport section
and so on.
Area wikis, and I think the IESG wiki, have "common problems encountered in
documents", and a number of areas have written guidelines to authors
comparable the rfc4181 guidelines for mib document authors.
[dbh>] It might be a good idea to encourage the development of template text
for specific sections, such as the YANG Security Considerations, and make
those available via the datatracker, in a common directory.
[dbh>] or a datatracker link to the common problems pages, which could host
related templates.
This might require some discussion with the IETF and/or IESG.

> Can you add a link (forget the URL) on the templates page?

I can add a copy, or if we do a maintained index page there, I could add a
link, certainly.  But I need to know where to point to ,;-)

[dbh>] The MIB Security Considerations are hosted on the OPS wiki (and I
copied them into the MIB template).
How the security considerations text reads is negotiated between the OPS and
SEC area directors.
Hosting it on the OPS wiki gives the Ads easier read/write access. 
We should talk with them about where they would like those text sections
hosted.

Best regards,

	Henrik

---

From: Benoit Claise <[email-masked]>
Date: Thu, 06 Jun 2013 10:42:02 +0200

> Can you add a link (forget the URL) on the templates page?
I like this idea.

Regards, Benoit.

> On Fri, May 31, 2013 at 10:28 PM, Henrik Levkowetz 
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>     Hi David,
>
>     > Tools.ietf.org <http://Tools.ietf.org> has them here:
>     [email-masked] <mailto:[email-masked]>

---

From: Benoit Claise <[email-masked]>
Date: Thu, 06 Jun 2013 11:24:19 +0200

Thanks David for this initiative.

I updated https://trac.tools.ietf.org/area/ops/trac/wiki/WikiStart, 
which can accessed for what I consider the primary page for MIB, 
https://www.ietf.org/iesg/directorate/mib-doctors.html.

See in line

> [email-masked]
BC> We actually discuss something related during the IESG retreat: what 
are the typical review DISCUSS points per area.
That lead to 
<http://trac.tools.ietf.org/group/iesg/trac/wiki/DiscussThoughts>
And it's also related to:

  * Collection of issues frequently found by Application Area ADs
    <https://trac.tools.ietf.org/group/iesg/trac/wiki/TypicalAppsAreaIssues>

  * Guidelines for Issues Found during TSVDIR Reviews
    <http://trac.tools.ietf.org/area/tsv/trac/wiki/tsvdir-common-issues>

 From this source of information, we might be able to deduce some 
template text for the specific sections/topics, as you said.

Regards, Benoit
> <[email-masked]>wrote:
>>> Hi David,
>>>