Techniques editing

Suggestions for work process

These are a few suggestions to get us going. Feedback is welcome.

Roles

WG members may be involved in a number of ways in the development of content for geo. These include:

• Developing new techniques content. Technique content is a set of information centred around a specific rule. The rule should be as concise and focused as possible on a single recommendation to the user. The content associated with a technique include supporting descriptions, user agent issues, and resource information. Resource information will be of various types, yet tbd, but may include such things as:
  • further information (questions the reader is likely to be asking themselves having read the technique)
  • sources (the sources of the information written up)
  • cross-references (other areas of potential interest)
  • background reading
  • useful prereading
  • links to more detailed implementation advice
  • other related links

  [We need to scope out how to handle resource information still]

• Proposing a structure for the presentation of the material to the user. This may include suggestions about how best to combine the information in the techniques in the context of a particular template to help the user find information intuitively and quickly - such suggestions would center on headings and groupings of content. It may also include the definition of a very different type of template - for example, we should be looking at an alternative checklist oriented view of the data rather than the fully descriptive view we currently have.
• Developing ancilliary information. This might, for example, be a section describing some aspect of the content that doesn't contain rules.
• Contributing feedback on the public-i18n-geo mailing list on content that others have written.
• Contributing proposals for rewording via the public-i18n-geo mailing list for passages in the current documents.
• Becoming an editor. (Involves adding xml content to the database and template documents using a validating editor and following the style guidelines, but also involves developing the style and structure of the various views and xsl transforms to achieve it.)

Techniques content development & submission

WG members can participate in a number of ways. The following summarises a possible process.

• WG members pick a topic from the suggested table of contents and develop content. A particular topic may be shared amongst more than one person - if so, the people involved should coordinate and discuss amongst themselves.
• Content should be developed, if possible, in the HTML format described below, and submitted to the public-i18n-geo mailing (the 'geo list') list for discussion/review. (We may develop alternatives, if people have suggestions.) Submissions should be HTML attachments - don't send HTML mail format.
• Other WG members (and possibly list listeners) contribute feedback on the content using the geo list, and the developer(s) modify the content and resubmit to the list.
• When any feedback has been incorporated into the content and the discussion dies down the content developer may request that the editors (currently Richard and Andrew) add the content to the xml database file.
• Feedback and suggestions for rewording are expected to continue, via the list, once the content is added to the database. Anyone can send proposals for rewording to the list. Incorporation of feedback may be done directly into the xml database by the editors, or the WG members may resubmit a new draft in HTML for review on the list.

HTML submission format suggestion

I would suggest we keep the HTML as simple as possible, presentationally-speaking, and use XHTML and utf-8 if possible. The key thing is to carefully use the appropriate divs, spans and class attributes to clarify the structure.

Below is a sample technique you can use as a template (copy and rework the source). Here is some CSS you can copy into the top of your HTML document to make it easier to read.

body { 
	background: white; 
	font-family: arial, sans-serif;
	}

div.technique {
	padding-left: 2em;
	}

div.short-name {
	margin-top: 3em;
	text-align: left;
	color: #005a9c; 
	background: white;
	font: 120% sans-serif;
	}

div.rule {
	margin-top: 1em;
	background-color: #ddeeff; 
	color: black
	padding: .5em;
	}

div.small-head {
	font-style: italic;
	font-weight: bold;
	margin-bottom: 0em;
	}

span.ua-type {
	font-style: italic;
	font-weight: normal;
	}

div.example {
	border-style: solid; 
	border-width: 1px ; 
	padding: .5em;
	color: #5d0091;
	background: #f9f5de; 
	border-color: #5d0091;
	width: 75%; 
	margin-top: .25em;
	margin-bottom: .25em;
	}

div.example { width: 95%; }

li p           { margin-top: 0.3em;
                 margin-bottom: 0.3em; }

.editor-note { font-style: italic; color: red; }

div.resources {
	border-style: solid; 
	border-width: 1px ; 
	padding: .5em;
	border-color: #5d0091;
	margin-top: .25em;
	margin-bottom: .25em;
	}

div.ua-issues{
	border-style: solid; 
	border-width: 1px ; 
	padding: .5em;
	border-color: #5d0091;
	margin-top: .25em;
	margin-bottom: .25em;
	}

span.resource-label, span.ua-type {
	font-style: italic;
	}
	

<div class="technique">
    <div class="short-name">Short title goes here</div>
    <div class="rule">The rule goes here</div>
    <div class="description">
        <p>Add paragraphs or other block elements here</p>
        <div class="example">
            <p>Include what you like in an example, but incorporate all examples in the div shown.</p>
            </div>
        <p>You can mix any number of examples with an number of other block elements in the description</p>
        </div>
    <div class="ua-issues">
        <div class="small-head">User agent issues</div>
        <div class="ua-issue">
            <p><span class="ua-type">Browser name and version: </span>Any block elements 
                you need here, but try to keep it simple, and start with the span.</p>
            </div>
        <div class="ua-issue">
            <p><span class="ua-type">Browser name and version: </span> You can have as many 
                ua issues as you want.</p>
            </div>
        </div>
    <div class="resources">
        <div class="small-head">Resources</div>
        <ul class="resource-item">
            <li><span class="resource-label">Resource type:</span> A description and link.</li>
            <li><span class="resource-label">Resource type:</span> As many more as you want.</li>
            </ul>
        </div>
    </div>