Closed Bug 44741 Opened 24 years ago Closed 20 years ago

Revisit/update HTML style guide

Categories

(mozilla.org :: Miscellaneous, task, P3)

Product:
mozilla.org
Component:
Miscellaneous
Platform:
Other
Other
Type:
task

Tracking

(Not tracked)

Status:
VERIFIED FIXED

People

(Reporter: BenB, Assigned: fantasai.bugs)

References

(
URL
)

Details

Attachments

(1 file, 3 obsolete files)

New Style Guide, again
21.38 KB, text/html
Details 
- It is written in an arrogant style
  Examples:
  - "Don't use StudlyCaps to separate words. Use hyphens. File names aren't
    Pascal code. Don't use underscores to separate words. Use hyphens. File
    names aren't C code."
  - "All pages must specify their foreground, background, and link colors.
    [Only 4 lines later:] The default fonts chosen by the user are just
    fine, thanks."
- It suggests bad HTML, instead it should mandate structural and valid HTML
  - "<ul>/<dl> for subsections"???
  - Use stylesheets instead of <body> attributes
  - ...
- "Each document's author should be listed at the top"
  We have an enforced "Last modified" footer. If necessary, add the author
  there.
  Apart from that, the "Content" section is IMO OK in general.

Also, make sure the "Mozilla menu" and the style guide itself follow the rules.
If you want, I can fix this bug apart from the last and third last line.
Attached patch patch to fix (obsolete) — — Splinter Review 

    
    

    
  
I just attached a patch. Can someone r= and I'll check it in?

    
    

    
  
I would add a rule at the top of the style guide saying:

"All pages must validate as HTML 4.01 Transitional or Strict".

See also bug 151557.

    
    

    
  
Stealing bug.
Assignee: endico → fantasai

    
    

    
  

      
      
      
      

        Attached file
          
        New Style Guide (obsolete)
        — 
      

    


  
New style guide. Has been under review for over a year; I hope that's enough?

        Attachment #16963 -
        Attachment is obsolete: true

        Attachment #16968 -
        Attachment is obsolete: true

    
  
Status: NEW → ASSIGNED
Depends on: 152104

    
    

    
  
> *No inline styles*. The <code>style</code> attribute is banned
> from mozilla.org pages with two exceptions: <code>float</code>
> and <code>clear</code>. Use semantic markup and either
> <code class="markup">&lt;link&gt;</code>ed style sheets or
> <code class="markup">&lt;style&gt;</code>.</p>

just when is inline style banned? I disagree with this rule, and also the no
color rule. See http://www.mozilla.org/newlayout/bugathon.html

and btw, style is not code. use <tt> instead

> Eschew marketing obfuscation.

This rule does apply to end-user doc, I hope?

I wouldn't be too thrilled about following the style guide until we have a
pretty site-wide stylesheet. So when can I get it?

    
    

    
  
> just when is inline style banned? I disagree with this rule, and also the no
> color rule. See http://www.mozilla.org/newlayout/bugathon.html

Use a class or ID. It's cleaner and in nearly all cases more appropriate.

The color rule stays. If you need a specific color, you follow the rules for
making sure you *get* that color--and a contrasting background to go with it.

> and btw, style is not code. use <tt> instead

'style' is an attribute. It is HTML /code/.
Other than requesting a font change, <tt> is semantically meaningless and
therefore should be avoided.

> This rule does apply to end-user doc, I hope?

Not to marketing docs, no. But I hope it would apply to end-user documentation.

> I wouldn't be too thrilled about following the style guide until we have a
> pretty site-wide stylesheet. So when can I get it?

Bug 152104 is for style sheets. It's marked as a dependency for a reason.
As for *pretty* style sheets, you'll either have to design them yourself or
wait until someone else does. Nonetheless, by following the style guide, you'll
ensure that all future pretty style sheets will prettily take effect on your
pages.

    
    

    
  
"style" here refers to an HTML attribute, not a piece code. Similarly if I say
"use <span> instead of <font>", I am refering to HTML elements. The < and > here
help improve readability, not to denote actual HTML code.

I've given some serious thoughts to your reasoning and the style guide makes a
little more sense now. Still, following it completely is just too much hassle.

    
    

    
  
> "style" here refers to an HTML attribute, not a piece code.

Point taken. However, <code> is the closest I can get without inventing a new
tag. I'll take it up with Hixie, though, since you insist.

> Still, following it completely is just too much hassle.

Explain.
(I would advise, however, exploring the Use Style menu on
  http://www.escape.com/~fantasai/mozilla-reorg/mozilla.org/ and
  http://www.escape.com/~fantasai/mozilla-reorg/mozilla.org/roadmap.html
first.)

    
    

    
  

      
      
      
      

        Attached file
          
        New Style Guide, again
        — 
      

    


  
Edited out a few sections so maybe we can get this up soon.

        Attachment #127844 -
        Attachment is obsolete: true

    
  

        Attachment #134687 -
        Attachment mime type: text/plain → text/html

    
    

    
  
*** Bug 225803 has been marked as a duplicate of this bug. ***

    
    

    
  
Should this be a webmaster bug?  I missed it when searching because of that.

    
    

    
  
One minor update--the name of the organization is now the Mozilla Foundation,
not mozilla.org.

    
    

    
  
> Use <a name="anchor-name">.  Linking to an ID isn't supported in many browsers.

> Pages must look decent in NS4+, MSIE4+, and Mozilla.

Don't NS4+, MSIE4+, and Mozilla all have support for linking to an id (I don't
have Windows right now, and can't test MSIE4)?  Assuming they do, shouldn't we
use linking to IDs for future XHTML compliance?

    
    

    
  
NS4 doesn't support ID linking. Neither do a lot of other older browsers--which
is what some people upgrading to Mozilla (and therefore navigating through the
website) will be using.

    
    

    
  
I stand corrected--I thought I had tried with NS4, but I guess I'd been using 6
or 7.

    
    

    
  
Just re-added bits about the markup reference (which is now up, though it needs
more examples). I consider this the mozilla.org Documentation Style Guide
version 2.0 FINAL, and this bug is fixed. :)
Status: ASSIGNED → RESOLVED
Closed: 20 years ago
Resolution: --- → FIXED

    
    

    
  
v.

fantasai, can you announce this to MozillaZine? doc contributors don't all watch
Bugzilla and may miss the new markup reference.
Status: RESOLVED → VERIFIED

          You need to log in
          before you can comment on or make changes to this bug.
        






  

    
  







  

    

      
Attachment

      

      
      
      
      
    

    

      

        

          

            
General

            

              Creator: 



            

            
Created: 

            
Updated: 

            
Size: