Language and text styles for Help screens

From PGVWiki
Jump to navigation Jump to search

Use bold text to make options stand out more, and remove embedded quotation marks where the use of bold text seemed better.

try to ensure that the text is valid xhtml. Thus, all HTML tags have to be lower-case, the tag "
" should be "
" , and you need those "", "", "", etc. closing tags.

Use " ". This adds extra spaces in some places so that the text is more readable. " " is also used to ensure that text that is a unit (dates, for example) stays together when the size of the window is adjusted.

Avoid the use of dashes because the text just reads better without them. In the case of ranges (e.g.: 1-31) it's better to write out the range (e.g.: 1 to 31) because that way of expressing them is universally understood. Please remember that not only native English readers consult the English Help text.

Italicize file names, especially when there's also a directory name. When writing about any PGV file that's in a directory other than the base directory, you should include the directory name. This avoids confusion. Thus, you should write about "languages/extra.xx.php" and not "extra.xx.php".

Names of reports, lists, fields, options, etc. need to be capitalized. Remember that when discussing an option, field, etc. the word "field" or "option" isn't part of the name and therefore should not be capitalized.

Language and country names are always capitalized in English. For example, it's always "Hebrew this or that" and not "hebrew this or that".

Acronyms are always capitalized. Since "GEDCOM" is an acronym (its meaning is explained in the Help text and at this URL: http://homepages.rootsweb.com/~pmcbride/gedcom/55gcint.htm ), it's always written as "GEDCOM", and more than one of them are always referred to as "GEDCOMs". This looks odd, but is just the way it's supposed to be.

To be strictly accurate, "GEDCOM" should always be referred to as "GEDCOM file" because "GEDCOM" describes a file format and not the file itself. A long time ago, I went through the entire Help text and replaced many such occurrences with "database" or "genealogical database" or "GEDCOM file". This task is ongoing, and far from complete. I guess it's time to do this again. However, "GEDCOM" can't be avoided altogether.

"PGV" should be avoided. The name of the program is "PhpGedView", with exactly that capitalization.

American spelling and grammar rules apply. Thus, it's "capitalize" not "capitalise", "color" not "colour", etc.

Commas and semicolons: Well, that depends on whom you listen to. However, when there are more than two list entries, they should always be separated by commas. In such lists, the penultimate entry (the one preceding "and" or "or") also gets a comma. The abbreviation "etc." indicates that a list is incomplete, so the entry preceding that "etc." also gets a comma. "etc." needs at least two preceding similar list entries. When there's only one, it indicates that the author knows that there should be similar entries, but he couldn't think of any. (I'm not going to do his thinking for him.)

We never use "and/or". It's one or the other, and "or" usually implies "and"; "and" never implies "or". When "or" is used in lists where you are permitted to make only one choice, you always need to say so in the context.

We avoid using "his/her", "(s)he", etc. In traditional English, the masculine form always includes the feminine. Thus, when we're talking about the Administrator or the user (notice the capitalization here?), we can legitimately use "he", since we all understand that PhpGedView is not restricted to only male Administrators or users. For variety, we sometimes use "she", but NEVER in the same paragraph.