|
Replies:
3
-
Last Post:
Nov 15, 2007 4:25 PM
by: alysson
|
Threads:
[
Previous
|
Next
]
|
|
Posts:
58
From:
US
Registered:
12/7/06
|
|
|
|
Doc Style Guide Update: Chapter 7 and beyond
Posted:
Oct 16, 2007 2:30 PM
To: Communities » documentation » discuss
|
|
Hi--
Per Rainer's suggestion, I've started a new thread for style guide update discussions.
I have finished incorporating the changes into Chapter 7, "Writing for an International Audience," in the OpenSolaris style guide. The changes are moderate.
If you have the time and the inclination, please review the changes, which are marked with change tracking. Any feedback is welcome. To access the chapter, go to:
http://opensolaris.org/os/community/documentation/reviews/
I'd appreciate receiving your feedback by October 30.
I'll summarize the changes here. If you would like to know more about why a specific change was made, feel free to ask. I'd be happy to provide details.
The updated chapter includes:
* New guidelines
* Clarification of existing guidelines
* More examples
* Bug fixes and consistency improvements
Some of the specific changes include the following:
* For accuracy, changed instances of "American English" to "U.S. English"
* Clarified guidelines about avoiding metaphors
* Added section on not using foreign terms
* Clarified guidelines about using the word "available"
* Rewrote section on using abbreviations and acronyms
* Added guideline about not using "Yes" or "No" in table data because they are problematic when translated into some languages
* Refined the index
Thanks so much for your help!
Alysson
--
Alysson Troffer
Technical Editor
Sun Microsystems, Inc.
|
|
|
Posts:
651
From:
CA
Registered:
6/14/05
|
|
|
|
Re: Doc Style Guide Update: Chapter 7 and beyond
Posted:
Oct 30, 2007 5:08 PM
in response to: alysson
|
|
Alysson Troffer wrote:
> Hi--
>
> I'd appreciate receiving your feedback by October 30.
Can we make that this coming Monday? I have no idea where the month
went. :-(
Rainer
--
Mind the gap.
_______________________________________________
docs-discuss mailing list
docs-discuss at opensolaris dot org
|
|
|
|
|
Posts:
651
From:
CA
Registered:
6/14/05
|
|
|
|
Re: Doc Style Guide Update: Chapter 7 and beyond
Posted:
Nov 4, 2007 5:35 PM
in response to: alysson
To: Communities » documentation » discuss
|
|
Greetings.
Again, my apologies for being late. It's been quite a month. I'm still trying to figure out where August went, and now it's already November.
I found very little to nit-pick on this revision. Another job well done. :-)
The few notes I have are:
Contents - still list "Avoid Abbreviations ..." I suspect this is a tool issue and will go away when the segment actually gets dropped.
p. 16 - Under "Do Not Arbitrarily ..." The second sentence starts with "Nor should you..." I would suggest changing it to: "...in your document, nor should you..." I think this is less awkward (and satisfies the rigorous enforcers of the "Do not start a sentence with..." folks).
Index: Under "international audiences", the first entry is "abbreviations and acronyms and," This seems awkward with the double "and." I'm not sure how best to clean it up; I have a few different ideas. The easiest may be to change the first "and" to a comma. Or maybe just drop the second "and" ??
That's about it. I must admit that I did not read through the entire chapter, word by word, with the usual plodding diligence I use for these reviews, so I'm hoping nothing has slipped past. Again, my apologies.
Rainer
---
Mind the gap.
|
|
|
|
|
Posts:
58
From:
US
Registered:
12/7/06
|
|
|
|
Re: Doc Style Guide Update: Chapter 7 and beyond
Posted:
Nov 15, 2007 4:25 PM
in response to: rheilke
To: Communities » documentation » discuss
|
|
Hi Rainer,
Thanks for reviewing Chapter 7. I'm grateful for your feedback. See my replies inline.
Cheers,
Alysson
>Again, my apologies for being late. It's been quite a month. I'm still trying to figure out where August went, and now it's already November.
Well, I don't even know where the year went!
>I found very little to nit-pick on this revision. Another job well done. :-)
Thanks. :-)
>The few notes I have are:
>
>Contents - still list "Avoid Abbreviations ..." I suspect this is a tool issue and will go away when the segment actually gets dropped.
Yep. It's another artifact of change tracking. It will go away when the changes are accepted.
>p. 16 - Under "Do Not Arbitrarily ..." The second sentence starts with "Nor should you..." I would suggest changing it to: "...in your document, nor should you..." I think this is less awkward (and satisfies the rigorous enforcers of the "Do not start a sentence with..." folks).
Sounds good. I'll go ahead and change that.
>Index: Under "international audiences", the first entry is "abbreviations and acronyms and," This seems awkward with the double "and." I'm not sure how best to clean it up; I have a few different ideas. The easiest may be to change the first "and" to a comma. Or maybe just drop the second "and" ??
Good catch. I agree it's awkward. I'll go ahead and drop the second "and."
>That's about it. I must admit that I did not read through the entire chapter, word by word, with the usual plodding diligence I use for these reviews, so I'm hoping nothing has slipped past. Again, my apologies.
No need to apologize. Any amount of time and effort you can provide is much appreciated.
|
|
|
|
|
