6:56 a.m.
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
7:07 a.m.
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
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
7:47 a.m.
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
> jboss-as7-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
_______________________________________________
jboss-as7-dev mailing list
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
7:13 a.m.
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
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
5:44 p.m.
h3++! Sentence case is better than Title Case.
----- Original Message -----
From: "Kabir Khan" <kabir.khan(a)jboss.com>
To: "JBoss AS7 Development" <jboss-as7-dev(a)lists.jboss.org>
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
jboss-as7-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
--
Misty Stanley-Jones, RHCE
Content Author, ECS Brisbane
☺: misty (Freenode IRC) ✉: misty(a)redhat.com ☏: +61 7 3514 8105 ☏: 88105
1:26 a.m.
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 <misty(a)redhat.com> wrote:
h3++! Sentence case is better than Title Case.
----- Original Message -----
> From: "Kabir Khan" <kabir.khan(a)jboss.com>
> To: "JBoss AS7 Development" <jboss-as7-dev(a)lists.jboss.org>
> 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
> jboss-as7-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev
--
Misty Stanley-Jones, RHCE
Content Author, ECS Brisbane
☺: misty (Freenode IRC) ✉: misty(a)redhat.com ☏: +61 7 3514 8105 ☏: 88105
_______________________________________________
jboss-as7-dev mailing list
jboss-as7-dev(a)lists.jboss.org
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
http://www.google.com/profiles/dan.j.allen#about
http://mojavelinux.com
http://mojavelinux.com/seaminaction
4676
days inactive
4677
days old
5 comments
6 participants
participants (6)
-
Carlo de Wolf -
Dan Allen -
Darran Lofthouse -
Kabir Khan -
Misty Stanley-Jones -
Pete Muir