Writing Style Guide

Updated 28-Jun-2024

This Document Part of a Complete Set of Style Guides

NOTE: figure out how to merge / reference this with markdown

Purpose of Text Style Guide

This Text Style Guide is for all textual communication including email, website, social media, brochures, ebooks, etc. as well as all printed material. This guide includes markup style and writing style.

---

Related Articles

• [Writing Style Guide]/writing-style-guide/)
• Pandoc, Markdown, XeLaTeX, EPUB
• [LaTeX for Markdown to PDF Conversion(/latex/)

---

Markup Style

Google Docs will be the primary repository of edited documents. However, there are additional editors which can be used, with documents saved in Google Docs and/or Dropbox. This is based on writer choice.

Markup using Google Drive

First, turn off the Smart Quotes and Automatic Substitution in Google Drive: (TOOLS > PREFERENCES). This needs to be done one time apparently for the user. So open a document, change the preference, close the document, then open other documents the setting should remain changed.

Markup using WriteBox

Writebox has several options including iOS, Android and Chrome apps as well as a generic webapp. It is fast and works well, though it does not have a side-by-side code/preview pane as Stackedit supports. Writebox also supports Google Drive and Dropbox storage. http://writeboxapps.com/

Standard Markdown Syntax

## H2 (subheads) ### H3 (sub-subheads) *italic* italic **bold** bold - Bullet - Bullet - Bullet - Bullet

> Quote (use this for callouts, note that this can wrap but if there is a new line, there needs to be a new greater-than sign and space. > For multiple paragraph asides, there needs to be another right angle bracket + space for each subsequently indented paragraph or element. > > This would be a second paragraph.

It is suggested to have a line space between paragraphs, but there should not be when dealing with such things as bulleted lists, such as:

> - This is the first bullet point > - This is the second bullet point

NOTE: the Quote format should be use for "Asides" or "Side Text". See also "Callouts/Pullquotes" section in the writing style guide below.

Tables

Item	Value
Item A	1600 USD
Item B	12 USD
Item C	1 USD

Specify column alignment with one or two colons:

Item	Value	Qty
Item A	1600 USD	5
Item B	12 USD	121
Item C	1 USD	| 234

(Left align, right align, center align)

Comments

We can use the extended HTML comment syntax. Note that there are three hyphens ("-") on the left side, and two on the right site. There should be no spaces between angle bracket, bang and hyphen on either side. For readability there should be a space separating the actual comment from the comment markup:

It is best to have an extra line spacing between the paragraph text, the comment, and the next paragraph text. When using this comment markup, in Multimarkdown and Pandoc, the comment is stripped out of LaTeX generation (given directives) but does not show up visibly in preview (though it does exist as an HTML comment, therefore invisible). In Stackedit.io the comment apprears as highlighted in red, but in Writebox it does not display (being treated like raw HTML markup).

Footnotes, Citations and References

To make things easy, we will use a simple footnote syntax for all citations, glossary terms and references: Some text¹. Final sentences at end of the paragraph.

Note that the ¹ name can be named anything (no spaces or numbers, prefer lower-case, short, descriptive of the source and the information.

Note also that there needs to be an extra blank line between these two lines, as well as an extra blank line to begin the next paragraph.

Third note: the footnote text should not be placed at the end of the edited chapter or book, but rather in the immediate vicinity of the initial footnote indicator. Automation software (XeLaTeX) will be used to move it to be an in-line footnote, an endnote, or a chaptered end-of-book footnote, as needed. Note that Stackedit is "smarter" than the markdown parsers we use on the website and also when generating pdf/epub. So we need to use the "dumber" syntax as found in the style guide.

There are two problems. The first is that the footnote link is not in a lowercase-plus-hyphen source description format. The second is that the URLs being put into the footnote text are not being marked up as URLs. Again, Stackedit can deal with this, so it looks ok in that editor, but other parsers cannot. Below is an example of your markup, and corrected version to use.

CURRENT MARKUP

... a staggering 400 million people -- are enrolled in some degree of English-language instruction². As more people learn to speak English...

CORRECTED MARKUP

... a staggering 400 million people -- are enrolled in some degree of English-language instruction³. As more people learn to speak English...

Note that the footnote marker is more descriptive of the source and kind of data, and the footnote itself has more descriptive link text as well as link markup.

Images

For a book, we want captions to display under the images, so use the following syntax:

![Figure Caption][image-filename.jpg "Figure Caption"]

Figure Caption

The Figure Caption is written three times (once for the ALT, once for the TITLE, and once for the Caption formatted in italics) it should be the same in all three cases.

The image-filename.jpg should be short, descriptive, lowercase and using hyphens between words ("-"). For various reasons regarding Kindle, all images should be .jpg files.

Note: There are more sophisticated captioning syntax but our wordpress plugin does not support this, so the text cannot be reused there. See also the Image Style Guide for more information about Image parameters and naming.

URLs

URLs should be used only in footnotes, not throughout the text.

Linked text

or if an email address is used, or a full website address:

Writing Style Guide

Writer Profile

The best writer is one who is a dedicated professional, has a thick skin, is detail-oriented and client-focused. This is the writer who can adapt their writing to the style and form needed, and understand that the writing required will help them develop professionally. Because we are focused, some might say picky or detail-obsessed, the writer and the writing reaches a higher level of specificity. This is then recognized by our readers and becomes a part of our brand.

Original Writing and Writing Style

All writing needs to be original. Paraphrase of ideas and facts is generally fine, especially where a link to the source can be found. These are not research papers, obviously. However, paraphrasing the sentence-level construction should not be done. No chapters or chapter sections should feel like rewritten articles found on other websites.

The simple approach is to have unique articles which have different meaning (and therefore will have to have different words). This is actually a lot less tedious than trying to find new ways of saying the same thing in different articles.

Writing should be robust and break away from a conventional guidebook style. Each chapter or chapter section should be less conversational and more straightforward and pithy. Easy generalizations that are overly positive should be dispensed with. Words such as amazing, wonderful, great, beautiful, stunning, and the like should be used sparingly, and more subdued adjectives and adverbs deployed, such as interesting, unique, worthwhile, and the like.

Significant factual detail - such as that found in historical sections of articles, or detailing climates, or a long list of airports - should be reduced or eliminated. It is enough to point to this information in other onsite articles or other websites. Organizing information in chapters and chapter sections so that each component tells a small but interesting and important story and provides insight and utility. The Lonely Planet guidebook style of including all detail at one-size-fits-all is not relevant for our purposes.

Chapter Style for Books

Chapters are usually around 2,000-3,000 words. In a 50,000 word book around 20 chapters is the appropriate target. However, the actual material may create shorter or longer chapters, as well as fewer or more of them. Chapters should be ordered in a way that they develop from each other and form a useful narrative. At the same time each chapter should be self-contained as much as possible, and should be meaningful if read alone. Reference to other chapters is entirely appropriate, e.g., "See the chapter on Risks and Hazards for more information about inoculations and other health precautions previous to travel to Thailand".

Inverted Pyramid

Facts and keywords should be near the front of the chapter, just as they should be up front in a given section and a given paragraph. Supporting information falls below. This is known as the inverted pyramid of journalism.

Cultural Elements and Teacher Experiences

Two kinds of specific information can be highlighted throughout the book in two ways: in a section near the end of most chapters, or using Asides. These are Cultural Elements and Teacher Experiences. Because culture touches nearly everything, even in chapters where it is not the focus, some elements of culture can be mentioned as asides or perhaps as a section near the end of the chapter. Teacher experiences are similar, that is actual experiences of actual teachers in any of the situations/logistics discussed can be presented, again as asides, or as a section at the end of the chapter.

Chapter Summary and Further Reading

At the end of each chapter should a summary of 4-7 one-sentence bullet points. This section should have a subhead of Chapter Summary. There should also be a subsection called Further Reading with 2-4 references. Some may be websites, especially Wikipedia pages, but it is strongly preferred to have full-length books or more extensive references. The goal is to provide a short, curated list of references in which the reader would find more information, rather than the same information.

Call-Outs (Pull-Quotes) and Asides

Some published works use include asides, which are generally used to introduce new but tangential material, examples or stories/references. Some works use call-outs (sometimes called pull-quotes), which emphasize a particular part of the text, usually a prominent statement or quotation. We want asides in our work, but want to avoid call-outs.

From one to five asides can be used in a given chapter. An example would be reference to a scientific study or publication that might illustrate a claim being made in the text. Another example would be illustrating a point by making reference to a prominent individual involved with the topic at hand. Asides should have references so that the reader may seek more information if they so desire. Asides can also be used for anecdotes and personal stories and experiences, as well as direct quotation.

We use the quotation markup to indicate an aside, as in:

> Quote (use this for callouts, note that this can wrap but if there is a new line (second paragraph), there needs to be another greater-than sign after two hard returns).

Section Style

Each chapter, article, press release or web page has several sections to it and each section should start with a subhead. These subheads are marked up with double hash marks and a space before the subhead, concluding with a space and double hash marks again. Note that the subheads need to include keywords, be clear and descriptive. After the subhead, a hard-return (ENTER key) should be used before the start of the first paragraph of the section. Subheads should be in Title Capitalization Format.

A section should be a logical division of the chapter which is not too long or too short relative to other sections. Sections can be 250-500 words on average, but they can be longer or shorter. The subhead itself should be clear, concise and descriptive of the content in the section, and should be meaningful to someone who is browsing through the book. Use of common terms is strongly preferred over terms that are themselves defined in the section. However, if the section is about that topic then the use of the term as well as a short description may be best for the subhead.

E.g., poor subhead: Krabi Krabong, better subhead: Krabi Krabong - Thai Weapons Martial Art; best subhead: Thai Weapons Martial Art - Krabi Krabong. Having the more common term of Thai Weapons Martial Art come first is better for the reader as well as online SEO of this section.

Note: the Editor/Publisher can help with Headers and Subheads, don't worry too much about this.

A section should be somewhat self-contained. That is, the section would make sense if read on its own. Sections should be in order of more general to more specific, as well as more important to less important. The first paragraph of the section should be descriptive of the content in the section and a general statement of that content. However, language such as "this section is about..." should be strongly avoided. (These formulations are unnecessary and represent a more academic style.)

Paragraph style

Paragraphs are roughly 4-5 sentences in length and should be thought of as a coherent subsection of the given section they are in. Individual writing style may have more say over paragraph-level organization. Between two paragraphs should be two hard-returns (ENTER key strokes).

Spelling, Grammar and Punctuation

It is best to avoid single quotes and double quotes as much as possible, especially when they are used semantically, e.g., to change the meaning or offset the words as being not fully literal. In most cases these marks are not needed, and when clarification of a term or some editorial distance, then the word so-called can be used or in some (few) cases, the italics formatting.

For book-length content, any one single English, e.g., American English, Australian English, British English, should be used throughout a given work. Pick one standard and stick to it, is the only firm rule. Spelling and usage should be consistent.

Overall, shorter sentences with few punctuation marks are strongly preferred. Each sentence should have no more than one idea, whenever possible. Avoid contractions such as it’s for it is, they’ve for they have, etc. In many cases the grammar can be changed to remove these words, or simply remove the contraction and replace with component words.

• American English Comma Usage: http://owl.english.purdue.edu/owl/resource/607/02/
• Differences between American and British English Comma Usage https://en.wikipedia.org/wiki/Comma#Differences_between_American_and_British_usage
• Use or discarding of Serial Comma should be decided upon and then consistently applied.

Diacritics

Please avoid use of any Diacritics: http://en.wikipedia.org/wiki/Diacritic

The reason is, people do not use them when they search in English, and Google in many cases treats them as different words. For example: http://www.google.com/trends/?q=Caf%C3%A9,+Cafe

This makes Vietnamese especially difficult, by the way. The French really cursed them. The diacritics have a lot of information but they are dropped when interacting in email/texting and the web.

Avoid all sub/superscripts. http://en.wikipedia.org/wiki/Superscript

These are generally formatting issues in Word (as well for the spelling corrections which add diacritics). You have to train/configure your text editor not to do these things.

Diacritics just don't work on the web in terms of search.

Word Choice, Voice, Pronouns and Reference

Word choice should be common language usage at all times, except in terms of necessarily technical discussion. Do not use a more obscure word when a plain, everyday word is available. Contraindications should become warning signs; assuage should be reduce; cultivated should become developed; realm should become area.

In most cases the word like is not appropriate when providing examples, but should be replaced with such as.

In nearly all cases a neutral, 3rd person voice should be employed. The imperative can be used, e.g., Contact someone for help. But the first and second person should be largely avoided, e.g., do not write You should contact someone for help.

Affect vs Effect: http://grammar.quickanddirtytips.com/affect-versus-effect.aspx

Use of Third Person

For gender pronouns with indeterminate reference (i.e., not to a specific known individual), use of the third person plural is preferred, e.g., use they or their for he/she or his/her.

Lists, Tables and Figures

The use of lists, tables and figures are strongly encouraged. When done well, these are very helpful to the reader and especially the potential customer who is browsing through the work. Whenever a list of things are discussed, a bulleted list should likely be included. Tables are very helpful for any systematically discussed comparisons or contrasts. Any pictures or drawings which can help illustrate the work should be identified, if only as an idea. All figures and tables need a caption in italic, such as:

Asean countries with English teacher salary and cost of living comparison

Citation, Reference and Copyright

Quotation should be avoided whenever possible. Paraphrase is ideal, however it is not always possible. For direct quotation, an in-line citation should be used, but full bibliographic information is not needed.

Use of Foreign Language Terms

Use of foreign language terms which are common should be formatted in italics (surrounded by a single asterisk, e.g., krengjai), along with a parenthetical original script and definition, e.g.,

Kreng jai (เกรงใจ) means being considerate or respectful, not wanting to bother someone.

Note that any definitions should also be included in the Glossary document. Please copy/paste the term (and definition) into the glossary as well. We will ensure that the Glossary definitions match the text within the chapters as part of the final editing process, so there is no need to manually keep these in sync.

Currency Codes and Currency Conversion

For currency, the capitalized, three letter currency code from the ISO 4217 specification: https://en.wikipedia.org/wiki/ISO_4217. This should be appended as a suffix after a space, e.g., 100 THB. If the currency needs to be spelled out, use capitalization, e.g., One Hundred Thai Baht. Avoid using the dollar, baht, pound, euro and other currency symbols. These are ambiguous and also not effective in search.

When discussing currency exchange rates, it is useful to mention (e.g., regarding the Thai Baht) the Bangkok Bank conversion page: http://www.bangkokbank.com/BangkokBank/WebServices/Rates/Pages/FX_Rates.aspx as well as the XE.com site (which is commonly used) http://www.xe.com/ as well as the approximation found in search engines Google, Yahoo, Bing, Wolfram Alpha, etc. For example, typing in "1 USD in THB" into search engines will produce a conversion rate calculation.

Another point is when trying to do currency conversion between two currencies which are not geographically or economically close to each other, it is best to use a more common currency as an intermediary. For example, THB to VND or IDR to THB. The most efficient approach is to change THB into USD while in Thailand, and then once arriving in say Vietnam, change USD into VND. The same would be true in traveling from Indonesia to Thailand, first change IDR into USD and then upon arrival in Thailand, USD into THB.

Punctuation

• Use of a parenthetical dash shall be " -- " (space, hyphen, hyphen, space).
• Only a single space after a period.
• There should not be any double spaces anywhere in the text (these can have negative effects when transforming from markdown to LaTeX).
• For apostrophe and single quote use only the character ('), and not a so-called fancy quote or the backtick. Many text editing programs do automatic substitution, but the characters are different from each other in terms of unicode, and cause problems.
• The same goes for double quote marks, use only (") and not fancy double quotes.
• There should not be any spacing or tab marks to begin paragraphs. These will be placed in the text upon transformation. Instead, there should be double-enter/return characters so that there is a blank line between each paragraph.

Notes on Interviewing

As a technique for interviewing, it is a good idea to get some yes/no questions, some “how important is”-type questions, and several open-ended questions that may result in useful information not previously known to the interviewer. Get permission in writing to use the interview. We can provide anonymity to our sources and still use their words and ideas, but we still need written permission. Anything said in public does not require the same level of permission, but it is always good to seek this out.

---

This Document Part of a Complete Set of Style Guides