GNOME.org
 

[HIG] Mini-Guidelines style

Here is an initial proposal for the style for the mini-guidelines. Alternative suggestions are welcome, but we need to have this firmed up by the time we have a firm outline: next Wednesday (specifically, 00:00 UTC on Thursday 16 August). Be warned: I'm going to take lack of criticism as positive feedback. :)
Each section should be an HTML page using fairly simple HTML constructs. This will allow us to do two things later: one, add CSS to make the pages appear distinctive and consistent, and two, construct a navigation system in an automated way.
[Note: I'm choosing HTML here rather than docbook or anything else because I know how to write HTML, and I think if we stick to the below instructions, it'll be fairly straightforward to transform the HTML into other formats as needed. I don't want us to get bogged down in learning docbook or anything like that just to write the mini-guidelines; we're on too short a timeline. 'Course, if I'm the only person who doesn't know how to write docbook, then I think I can pick it up pretty quickly. Again, though, I think it's more important for us to get the content written in a consistent way and we can figure out how to transform it later.)
The name of the section should be in an <H1> at the top of the page, as well as in the document title. These headers should _not_ include a section number, as we may want to rearrange the pages later. For example: 

<html>
<head>
<title>Menus and Toolbars</title>
</head>
<body>
<h1>Menus and Toolbars</h1>
Major subsections should be marked as <h2>, as follows. Again, these sections should not be numbered. 

<h2>Principles</h2>
Topics under these subsections should be marked as <h3>. No headers below <h3> should be present. 

<h3>Always show keyboard shortcuts</h3>
Body text should generally be marked simply as <p>; procedural instructions if any should be marked as <ol> so that each step is numbered, and other types of lists should be marked as <ul>.
Any quotes or paraphrases from other documents should be noted. I would recommend using a simple scheme for this like (Cooper, 1999) and having a single bibliography, but if anyone has a particular favorite reference style I don't feel strongly about it. Lengthy direct quotes from other documents, books, etc. should be marked as <blockquote> and noted.
Inline images (screenshots, etc.) should be included on their own paragraphs. The ALT text should include a brief description of the image. We may want to add figure captions inline in the text later. Do not include image formatting instructions, except height/width. Inline images should always be local; don't refer directly to an image on another site.
<p><img src="images/screenshot1.gif" alt="Screenshot showing a good example of keyboard shortcuts in the File menu">.
Use of <b> or <i> or <u> is fine where appropriate; no use of <font> should be allowed, nor any "align" or navigation aids; we'll add those later using CSS and scripts that somebody (perhaps me :) will write.
Tables are fine but should not include formatting commands such as "border=0", etc. Just cells and rows and we'll deal with the formatting later in a consistent way. 

Anything important I'm missing here, or objections to the above?

Adam
--
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]