[drupal-docs] Styleguide

[Anisa]

Actually, there are lots of pages in the handbook that use the word 
'Drupal'.  Someone take them out.  They violate the stated style 
guidelines.  ;p

Structure of a Basic Page
======================
(Navigation: Breadcrumb: Trail)
 Title - H1 or H2

[b]Target[/b]: (Who is this page for?  Developers?  Average users?)
Topics covered: (What is in this page?)
You need to know: (What should you know before reading this page, and 
links to find out more about it)

Related topics: (Links to related topics, in case the user may have come 
here looking for something else, or just good manners ;p)

Background Information: (blah.)

Topic 1 - H2 or H3
Step by step instructions.  OL (ordered lists).

Troubleshooting/common questions:

Topic 2 - H2 or H3
Text.

Troubleshooting/common questions:

[A line to signify the end of the help text]

Other sources of help: Link to any available videos, alternative 
documentation.

[Comments]
=====================================================

Only as a template for your average page.  Things like module pages can 
be treated a little differently.

Anisa.
Sleepy, still.


Anisa wrote:

> Addition, as per: http://drupal.org/node/15595
>
> Use 'your' not 'my' when refering to the user's drupal site. 
>
> Anisa.
>
> Anisa wrote:
>
>> Currently established style guide (http://drupal.org/node/15289):
>>
>>     * Don't use the words 'Drupal' or 'Handbook' in page titles
>>     * Use ordered lists for step by step instructions.
>>     * When directing someone to a place in their Drupal install, use
>>       this format: destination (<i>path &gt; to &gt; item &gt;
>>       destination</i>) (which will look like this: destination (path
>>       > to > item > destination))
>>     * When directing someone to a place in their drupal install, do
>>       not abbreviate.
>>     * If you refer to a module/theme/whatever, link to it once, but
>>       not too many times.
>>     * Enclose code samples within <code> tags.
>>     * Links should be embedded within normal descriptive body text.
>>     * Links should use this format: <a href="node/1234567"
>>       title="information">
>>     * Always spell check
>>
>> I would add the following:
>>
>>     * When refering to a place in a drupal install, always include
>>       the actual drupal path. (ex. not just path > to > item >
>>       destination, but also admin/node/configure)
>>     * Include references to relevant or related pages as much as
>>       possible.
>>     * Keep to the topic in the document.  If you are writing on topic
>>       C, and C requires knowing about A and B, make seperate pages
>>       for A and B.
>>
>> Anisa.
>> sleepy.
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050424/d900a3f0/attachment.htm