Documentation headers

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Documentation headers

kkhan
The capitalization of the headers in the docs is a bit arbitrary

Some Places We Do This
Other places use this

This needs to be standardized. Either we choose one of the two options or

h1 + h2: We Use This
h3++: We use this
_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation headers

Pete Muir
I think it's wrong to capitalize every word  except in the title of the guide. I have never seen this done in tech docs.

I am aware of two conventions.

1) "minor words" - conjunctions, articles, prepositions, pronouns are lower case, whilst nouns, verbs, adjectives, adverbs are capitalised. e.g. "JBoss Application Server 7 is a Extremely Nice Project." "JBoss Application Server 7 Runs in Eclipse Very Well"

or

2) All words are lower case except proper nouns (just like a sentence).  e.g. "JBoss Application Server 7 is an extremely nice project" "JBoss Application Server run in Eclipse very well".

I think option (2) is by far and away the best. I've looked at the Admin Guide and this is the usage there. There Getting Started Guide almost uses this. I noticed a couple of errors in the Getting Started Developing Applications Guide but this is the style I intended.

On 5 Jul 2011, at 11:56, Kabir Khan wrote:

> The capitalization of the headers in the docs is a bit arbitrary
>
> Some Places We Do This
> Other places use this
>
> This needs to be standardized. Either we choose one of the two options or
>
> h1 + h2: We Use This
> h3++: We use this
> _______________________________________________
> jboss-as7-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev


_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation headers

Darran Lofthouse
In reply to this post by kkhan
What is the standard for EAP docs?  It probably doesn't make any sense
to do something different.

Regards,
Darran Lofthouse.


On 07/05/2011 11:56 AM, Kabir Khan wrote:

> The capitalization of the headers in the docs is a bit arbitrary
>
> Some Places We Do This
> Other places use this
>
> This needs to be standardized. Either we choose one of the two options or
>
> h1 + h2: We Use This
> h3++: We use this
> _______________________________________________
> jboss-as7-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev

_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation headers

Carlo de Wolf
In reply to this post by Pete Muir
I used the same style as the JSRs.

e.g. "Specification of Transaction Attributes with Metadata Annotations"

Carlo

On 07/05/2011 01:07 PM, Pete Muir wrote:

> I think it's wrong to capitalize every word  except in the title of the guide. I have never seen this done in tech docs.
>
> I am aware of two conventions.
>
> 1) "minor words" - conjunctions, articles, prepositions, pronouns are lower case, whilst nouns, verbs, adjectives, adverbs are capitalised. e.g. "JBoss Application Server 7 is a Extremely Nice Project." "JBoss Application Server 7 Runs in Eclipse Very Well"
>
> or
>
> 2) All words are lower case except proper nouns (just like a sentence).  e.g. "JBoss Application Server 7 is an extremely nice project" "JBoss Application Server run in Eclipse very well".
>
> I think option (2) is by far and away the best. I've looked at the Admin Guide and this is the usage there. There Getting Started Guide almost uses this. I noticed a couple of errors in the Getting Started Developing Applications Guide but this is the style I intended.
>
> On 5 Jul 2011, at 11:56, Kabir Khan wrote:
>
>> The capitalization of the headers in the docs is a bit arbitrary
>>
>> Some Places We Do This
>> Other places use this
>>
>> This needs to be standardized. Either we choose one of the two options or
>>
>> h1 + h2: We Use This
>> h3++: We use this
>> _______________________________________________
>> jboss-as7-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
>
> _______________________________________________
> jboss-as7-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev

_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation headers

Misty Stanley-Jones
In reply to this post by kkhan
h3++! Sentence case is better than Title Case.

----- Original Message -----

> From: "Kabir Khan" <[hidden email]>
> To: "JBoss AS7 Development" <[hidden email]>
> Sent: Tuesday, July 5, 2011 8:56:06 PM
> Subject: [jboss-as7-dev] Documentation headers
> The capitalization of the headers in the docs is a bit arbitrary
>
> Some Places We Do This
> Other places use this
>
> This needs to be standardized. Either we choose one of the two options
> or
>
> h1 + h2: We Use This
> h3++: We use this
> _______________________________________________
> jboss-as7-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev

--


Misty Stanley-Jones, RHCE
Content Author, ECS Brisbane
☺: misty (Freenode IRC) ✉: [hidden email] ☏: +61 7 3514 8105 ☏: 88105

_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation headers

Dan Allen
Manning (publisher) was adamant about having their authors use Sentence capitalization for headings. O'Reilly and Apress appear to use the Title Case format.

Personally, I find the Sentence capitalization easier to read, and easier to get right (since that's how we write most of the time).

-Dan

On Tue, Jul 5, 2011 at 17:44, Misty Stanley-Jones <[hidden email]> wrote:
h3++! Sentence case is better than Title Case.

----- Original Message -----
> From: "Kabir Khan" <[hidden email]>
> To: "JBoss AS7 Development" <[hidden email]>
> Sent: Tuesday, July 5, 2011 8:56:06 PM
> Subject: [jboss-as7-dev] Documentation headers
> The capitalization of the headers in the docs is a bit arbitrary
>
> Some Places We Do This
> Other places use this
>
> This needs to be standardized. Either we choose one of the two options
> or
>
> h1 + h2: We Use This
> h3++: We use this
> _______________________________________________
> jboss-as7-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev

--


Misty Stanley-Jones, RHCE
Content Author, ECS Brisbane
☺: misty (Freenode IRC) ✉: [hidden email] ☏: <a href="tel:%2B61%207%203514%208105" value="+61735148105">+61 7 3514 8105 ☏: 88105

_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597



_______________________________________________
jboss-as7-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
Loading...