Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 08 Feb 2014 16:25:25 -0500
From:      John Baldwin <jhb@freebsd.org>
To:        freebsd-doc@freebsd.org
Subject:   Re: [PATCH] Use a bullet list for general policies
Message-ID:  <2667682.EQsnSbIC49@ralph.baldwin.cx>
In-Reply-To: <52F63858.3010202@FreeBSD.org>
References:  <201401311421.31347.jhb@freebsd.org> <52F63858.3010202@FreeBSD.org>

next in thread | previous in thread | raw e-mail | index | archive | help
On Saturday, February 08, 2014 02:59:52 PM Benedict Reuschling wrote:
> Am 31.01.14 20:21, schrieb John Baldwin:
> > Right now the internal policies page has a paragraph that lists the
> > project's policies inline in one big sentence.  I find this harder
> > to work with as if I'm looking for a particular policy I have to
> > scan the entire sentence.  I think in this case a bulleted list
> > works better.  The patch below changes it (note that I haven't
> > reordered them, and it may be that there is a better order, though
> > I'm not sure what it would be).  Any objections?
> > 
> > Index: head/en_US.ISO8859-1/htdocs/internal/policies.xml
> > ===================================================================
> 
> --- head/en_US.ISO8859-1/htdocs/internal/policies.xml   (revision 43698)
> 
> > +++ head/en_US.ISO8859-1/htdocs/internal/policies.xml   (working
> > copy) @@ -34,25 +34,18 @@
> > 
> > <h2><b>General Policies</b></h2>
> > 
> > -<p>Here you will find various things such as the -<a
> > href="new-account.html">New Account Creation Procedure</a>, -the
> > -<a href="expire-bits.html">Commit Bit Expiration Policy</a>, -the
> > -<a href="bylaws.html">Core Bylaws</a>, -the -<a
> > href="resources.html">Commit Bit and Project Resources Policy</a>,
> > -<a href="core-vote.html">Core's Voting Procedures</a>, -the -<a
> > href="fortunes.html">Fortune File Policy</a>, -the -<a
> > href="i18n.html">Internationalization Policy</a>, -the -<a
> > href="data.html">User Data Policy</a>, -the -<a
> > href="hats.html">Hats Term Limits Policy</a>, -and the -<a
> > href="../doc/en_US.ISO8859-1/articles/pr-guidelines/">Problem
> > Report Handling Guidelines</a>.</p> +<ul> +  <li><a
> > href="new-account.html">New Account Creation Procedure</a></li> +
> > <li><a href="expire-bits.html">Commit Bit Expiration
> > Policy</a></li> +  <li><a href="bylaws.html">Core Bylaws</a></li> +
> > <li><a href="resources.html">Commit Bit and Project Resources
> > Policy</a></li> +  <li><a href="core-vote.html">Core's Voting
> > Procedures</a></li> +  <li><a href="fortunes.html">Fortune File
> > Policy</a></li> +  <li><a href="i18n.html">Internationalization
> > Policy</a></li> +  <li><a href="data.html">User Data
> > Policy</a></li> +  <li><a href="hats.html">Hats Term Limits
> > Policy</a></li> +  <li><a
> > href="../doc/en_US.ISO8859-1/articles/pr-guidelines/">Problem
> > Report Handling Guidelines</a></li> +</ul>
> > 
> > <h2><b>The FreeBSD Documentation Project</b></h2>
> 
> Hmm, maybe we should group "Commit Bit Expiration Policy" and "Commit
> Bit and Project Resources Policy" together as well as the "Core
> Bylaws" with "Core's Voting Procedures" as they are related topics.
> The rest is pretty much standalone and I can't find any other better
> order. I can also live with Eitan's suggestion of having them in
> alphabetical order.

I did think about grouping them some, but I found that the categories
I was going to use (governance, inter-developer relationships) did not
lend themselves to clear separation as many of the individual items fit
into multiple categories, etc.

Also, this page is a bit of a dumping ground as it is.  I do think it
might make sense to have a page that looks a bit more like:

- Project Bylaws (rename the core bylaws to this)

- Team Charters
  - portsmgr charter
  - secteam charter
  - re charter (does this exist?)
  - clusteradm charter

- Policies
  - <much of the existing policy list>

Right now I think some of the charters are scattered into different pages 
which isn't but so helpful for someone who wants to get a sense of how the 
Project works and/or is organized.

-- 
John Baldwin



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?2667682.EQsnSbIC49>