[drupal-docs] Styleguide

[puregin]

On 24 Apr 2005, at 10:17 AM, Anisa wrote:

>  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

      Yes, that one puzzled me.   There's a couple of pages where 
'Drupal' or 'Handbook'
might be removed, but most of the occurrences seem fine as they are.  
It's tough to
write about something if you can't mention its name.

      We do need to agree to capitalize 'Drupal' and derivatives, except 
where the
occurrence is a literal reference (e.g. URL, filename, chunk of code, 
etc.)

      Anisa, I'm not sure what you're trying to do with the "Structure 
of a Basic Page"
bit that you included.  Could you explain your thinking?

      I would like to re-iterate that it's very important that we *not* 
include
any headers in handbook nodes (no <H1> ... <H6>)  The reason: headers
are about structure.  Structure should be sole domain of book module or
whatever else holds the content.    Putting header tags into a node
gives 'false structure' .    Subsections of a given section, therefore,
should always be constructed as a child of that section.

      In fact, perhaps we need a special filter for this situation.

      I have some additional suggestions for the style guide, but I'll
have to return to them tomorrow.

      All in all, great to see some actual progress on documentation.
My headache is starting to go away :)

     Djun

>
>  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.
>>>
>>>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
--
Djun M. Kim, Director                           
djun.kim at cielosystems.com
Cielo Systems Inc.                              
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379