Document style guide

[Paul Sutton <pa...@c2.net>]

There's recently been some debate over a few different ways of laying out
HTML. Now, we had much fun over a year ago getting a style guide together
for source code, but now we know how to layout the code and it is working
well. While some of the code layout guidelines help to avoid making coding
errors, many are purely for aesthetic reasons. So having a style guide for
the aesthetics of our documentation (both as seen by end users and when
writing HTML) is not unreasonable. Plus many more people see the
documentation than ever view more than a few lines of code, so a
consistent and attractive style might give us a better image. But on the
other hand people may feel it is unnecessary, hence the first item. 

The idea of this message is to see if there is interest in a style guide,
and if so, to see if there are any other areas which need to be voted on
(I've listed a few possible candidates below as 4-8). Then finally we'll
vote and see what the results are.

//pcs

Items under discussion
----------------------

  0.   Do we need a style guide for documentation?
   a.  Yes
   b.  No

  1.   Case of HTML tags

   a.  Use upper case. E.g. <STRONG>
   b.  Use lower case. E.g. <strong>

  2.   Layout of HTML attributes inside tags

   a.  Place attributes on different lines. E.g.

         <A
            HREF="directive-dict.html#Status"
            REL="Help"
         >Status</A>

   b.  Place attributes on single line unless wrapped by end-of-line. E.g.

         <A HREF="directive-dict.html#Status" REL="Help">Status</A>

  3.   Capitalization of Apache's hostname and email address

   a.  Lowercase. E.g. http://www.apache.org/, ...@apache.org
   b.  Mixed case.  E.g. http://WWW.Apache.Org/, ...@Apache.Org


Other Possible Style Items
--------------------------

  4    HTML version compliance; use of non-standard extensions
  5    Style sheets
  6    Indentation of containers (e.g. <UL>, <DL>, BLOCKQUOTE>) content
  7    Use of font styles vs. phase styles (e.g. <B> vs. <STRONG>)
  8    Language (UK vs. US spelling and conventions, for instance)

Re: Document style guide

[Marc Slemko <ma...@worldgate.com>]

On Sun, 15 Feb 1998, Paul Sutton wrote:

> Items under discussion
> ----------------------
> 
>   0.   Do we need a style guide for documentation?
>    a.  Yes
>    b.  No

Yes, and all the below things are a start.

> 
>   1.   Case of HTML tags
> 
>    a.  Use upper case. E.g. <STRONG>
>    b.  Use lower case. E.g. <strong>
> 
>   2.   Layout of HTML attributes inside tags
> 
>    a.  Place attributes on different lines. E.g.
> 
>          <A
>             HREF="directive-dict.html#Status"
>             REL="Help"
>          >Status</A>
> 
>    b.  Place attributes on single line unless wrapped by end-of-line. E.g.
> 
>          <A HREF="directive-dict.html#Status" REL="Help">Status</A>
> 
>   3.   Capitalization of Apache's hostname and email address
> 
>    a.  Lowercase. E.g. http://www.apache.org/, ...@apache.org
>    b.  Mixed case.  E.g. http://WWW.Apache.Org/, ...@Apache.Org
> 
> 
> Other Possible Style Items
> --------------------------


> 
>   4    HTML version compliance; use of non-standard extensions
>   5    Style sheets
>   6    Indentation of containers (e.g. <UL>, <DL>, BLOCKQUOTE>) content
>   7    Use of font styles vs. phase styles (e.g. <B> vs. <STRONG>)
>   8    Language (UK vs. US spelling and conventions, for instance)

Go for Canadian spelling, eh?