[drupal-docs] Styleguide

[Anisa]

puregin wrote:

>
> 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.
>
Nah, they can all be taken out.  As it says in the style guide, this is 
the Drupal Handbook.  It's pretty bloody obvious that it's all going to 
be about Drupal.  The content is fine (she says, not really looking ;)), 
but the titles should be changed.

>      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 believe, personally, that if every page in the handbook looked the 
same, it would be easier on the user.  We could provide a lot of the 
same information that makes up good documentation (cross-referencing, 
for example) in a condensed format.  Also gives a visual cue to any 
budding documentation writers that this is the kind of stuff we'd like 
to see in the handbook page.

>      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.
>
Hmmm...  I see what you mean.

Basically, I had it like this:
Page A
 >Topic 1
 >Topic 2

You suggest it look like this:
Page A
 >Page A.1
 >Page A.2

Hmmmmm....

>      In fact, perhaps we need a special filter for this situation.
>
Hmmmmmmmm....  This requires more thought.

>      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 :)

It is rather nice, isn't it?  :)

I definitely feel we have gotten out of a quagmire.

Anisa.