Archive | Publishing

Writing Style Guide

This Document Part of a Complete Set of Style Guides

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. 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 text1. Final sentences at end of the paragraph.


  1. Here is the text of the footnote. Note that the [^footnote] 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 instruction2. As more people learn to speak English... 

  2. 2010 data, http://english.people.com.cn/90001/90776/90882/7093494.html CORRECTED MARKUP ... a staggering 400 million people -- are enrolled in some degree of English-language instruction3. As more people learn to speak English... 

  3. China Daily 2010 data English course enrolment 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 

Video Workflow – Free Tools

The best part of video is how convenient it has become. However, it is still a lot of work. The tools I like to use also need to be fast... and free. This is an important aspect of liberty. Even for short videos there is usually a combination of images, video clips and audio that […]

Continue Reading

Audiobooks – Mono in a Stereo World

Audiobooks are generally a neglected/emerging area in much of the world. If one is in the US, of course it is less of a problem, but even Apple has a half-assed approach currently. Apple / iOS / OSX While it appears Apple is trying to get its act together, it is a far distance from […]

Continue Reading

Publishing Genre

While there is quite a bit of literary genre everywhere alive and well, there are certain publication genre which are not. The Chapbook (still popular) and the Almanac(k), as well but we don't hear about it much anymore. Chapbook in the Age of Print-on-Demand The Chapbook seems like a wonder in the age of Print-on-Demand. […]

Continue Reading

Style Guide

This is a permanent page about style guides used in writing and for marketing. In particular there two kinds of Style Guides: - Brand Style Guide (for product designers, pr types, and all public and corporate communications) - Publishing Style Guide (for writers, editors, publishers) These two intersect and the Brand Style Guide should refer […]

Continue Reading

Atom Editor

Update Mar-2018 - I'm going with Caret which is both a desktop markdown app, as well as an (unrelated) chromeOS app. I still like Atom, however, it's still great! For Open Source, Atom is a great editor (Brackets is another). But there are still a few warts, and of course plugins must be used for […]

Continue Reading

Markdown Specifications and Editors

Note: This post is nearly two years old and in need of a revamp. It is too longish but most of the information is there. Need to do a few things: Remove any redundancy Reorganize with a table of contents Rename markdown: Original, Standard, Github, Stackedit, Extra, Markua Note that standard is simply the specific […]

Continue Reading

Publishing Workflow

In rough, this is the publishing workflow that gets books from conception/marketing to publishing and distribution.

Marketing, Marketing, Marketing

Publishing a book or journal is first and foremost a marketing decision. That is, it has to in some way reach and appeal to a readership, and that includes who are the distributors (electronic and print), who the competitors, and who the market, including market size and pricing considerations.

Commitment and Timeline

Once really good reasons for publishing are discovered, then there needs to be an identification and commitment to the resources needed to get the book written, composed, and typeset. This includes identifying writers, sources of material, editors, photographers and/or illustrators.

Collaborative Documentation and Process

At this point, when people agree verbally and by handshake (real or virtual) then the set of documents can be produced and the stages of conceptualizing and concretizing the book begins.

Brainstorming and Contract Drafts

In step 1 there are three usually parallel discussions:

  • Legal: This is the publishing contract, and includes who pays, when and how much, and who receives, when and how much, financial and intellectual property benefits
  • Content: This is the initial brainstorming document, which has content that are then organized into chapters and chapter outlines
  • Market: Contents and Scope has a marketing part and a finalized table of contents that comes out of the content brainstorming document

Contract Signing, Chapter Outlines, Style Guide, Progress Spreadsheet

At this stage contracts are signed. Next, chapter outlines are generated from the Contents and Scope document (each becomes an individual document for managing the writing/editing process), including pseudo-chapters such as the introduction, any indices, appendices, and glossary.

Next a style guide is finalized, which includes authorial voice, kind of English to be used (US English, UK English, etc.), capitalization and abbreviation rules, as well as formatting style.

A figures spreadsheet is created, to be filled in with any images, figures or tables to be deployed in the book. Some of these are known ahead of time, others are thought of as chapters and sections are completed, or as artwork is discovered or created. This spreadsheet also tracks the source of any images, drawings, tables (and table data) to be used.

A progress spreadsheet is created, including (at least provisional) due dates for chapter draft completion.

Publication Kickoff

The writing, researching and figure generation begins in earnest. I prefer meetings every two weeks, though once per week is much better and will move things along. Working with professionals it is possible to do once per month meetings, but less time between meetings usually spurs work along.

Publication Editing

There are of course several kinds of editing, including copyediting, fact-checking, and also layout and design editing. These should happen in an ongoing process rather that waiting until an endpoint. Memories fade and even written notes are neglected. Make changes as the need for changes arise.

Publication Finalization

A final approval of the document (preferably confirmed in writing/email) should signal the end of the writing and the clock starting on the publishing process. Getting a draft printed via Print-on-Demand is a good next step to see what kind of errors there are and read something physically in book form.

From here it becomes a matter of finalizing the product, getting it vetted by distributors and the submission process. Report milestones achieved on a weekly basis to keep everyone informed of the progress toward publication. Send out draft versions to reviewers.

Technical Aspects

I've left out a bunch of technical aspects in terms of tools. Partially because people and organizations can use different tools, this is not important. However, for good quality control and a beautiful product, the use of XeLaTeX for typesetting is vital.

Life is a kind of Library

A famous writer (Borges) once said that he imagined the afterlife (or more precisely Paradise) to be a kind of library. However, what occurs to me now (in at once a banal and deeply moving way) is that not only the afterlife, but Life is a kind of Library. I mean this both as metaphor […]

Continue Reading

Screen Promiscuous – Publishing

Yes, screen promiscuous, a term I did not know before reading the piece on Snowpiercer in the LA Times. Short and Longform Trends As John Borthwick reports there are two trends in media consumption seemingly at odds, lots of micro/immediate shortform content being consumed and reflected, as well as longform, quality content that has significant […]

Continue Reading