page: Editorial style guide

[wion]

URLs

• Front: https://docs.textpattern.com/brand/editorial-guide
• Back: https://github.com/textpattern/textpattern.github.io/blob/master/brand/editorial-guide

Explaino

A veritable editorial style guide for Textpattern that guides the development of all content in project platforms. The guide will be written using the popular convention of referring to an existing baseline reference, but providing our own local overriding guidelines where different from the baseline, or which might need special highlighting for collaborator attention.

Resources to use

The baseline references for Textpattern platforms are:

• New Oxford Style Manual, 3rd edn, 2016 (Wion has a copy)
• Oxford English Dictionary (any abridged version having the words you need is fine)

Reminders

• title
• lists punctuation
• brand name usage
• OED spelling distinctions
• quotation mark usage
• code vs. URIs vs. file tree usage and formatting

To-dos

• [ ] Consider which topics may needed directly stated in the local doc
• [ ] Look at clean style guide examples
• [ ] First draft for review

[philwareham]

OK sounds like a good idea, I'm going to spend some time on Saturday prepping Jekyll stuff. Not got much time until then.

[wion]

NTS: Make a new section in editorial style guide for 'special docs syntax' and add rule for tables, with following example:

notextile. <div class="tabular-data">

Textile table markup

notextile. </div>

Can someone assign this issue to me? Thanks.

[wion]

I've started work in this direction, for the editorial parts anyway, by creating a /brand folder to consolidate focus and effort... https://github.com/textpattern/textpattern.github.io/tree/master/brand

It has an index to help shape our thoughts, and rope various distributed resources together, at least to link to them, which I expect will change as we go... http://docs.textpattern.io/brand/

From that we can later create the universal footer list as noted in issue #28 once the specific links are clear. Or maybe this index just ends up being the link. Whatever.

My immediate focus, as it concerns this issue, is to get the editorial style guide in shape and close this ticket... http://docs.textpattern.io/brand/editorial-style-guidelines

[wion]

@Bloke, @philwareham, @petecooper,

I'd like to propose a significant change to the editorial style guide that has implications for new xml:lang="en", lang="en", and <meta name="language" content="en" /> values in Textpattern websites.

The change concerns what language conventions are used for English word spellings, for the most part. As you may be aware, English-language style guides around the world — from old academic institutions like Oxford, to international organizations like the International Organization for Standardization (ISO), to popular media entities like the New York Times — all say one thing or another about what is right or what their people should follow in terms of word usage. Even the world's leading style guide authorities, like AP's, Chicago Manual of Style, and so forth don't agree on many things. This can make it overly difficult and annoying for everyone else trying to create their own guidelines for international use.

As you know, we've been using a rule that says "British English" conventions are the baseline for spelling and punctuation. But our reasons for that have been rather wishy-washy (albeit founded), and particularly as current Txp real estates don't specify en-GB in any of the language designators noted above. If we adopt a baseline convention, that's where it should be designated, for the benefit of machines and uppity authors/editors who want to challenge a style guide rule. We can say, "Look, even SkyNet understands what we're doing."

But British English isn't any more helpful than saying "Use any English convention you want.", because even in Britain things are changing; while many entities in that region still write words with -ise, for example, or use single quotation marks instead of double, there's an increasing number that are starting to use -ize and double quotation marks instead of single. So using "British English" as a designator just localizes (from international to GB) the same dilemmas about convention.

I think I see a logical way forward, which I'm probably going to initiate at CSF too. The IETF has a language tag compatible with HTML: en-GB-oxendict, which basically means 'British English but specifically favoring the conventions of the Oxford English Dictionary'. Which we might safely extrapolate to the Oxford publishing house in general, which puts out other editorial references too.

As it turns out, Oxford — as well the ISO, United Nations, and many other international organizations — favors using -ize (instead of -ise) because the influence behind "-ise" is French, not the original Greek root, -izo, of most -ize verbs. Makes sense. All other words spellings used in mainstream British English (-yse, -tre, -amme, -ense, etc) are the same in Oxford, so no change there.

Ultimately it doesn't matter how words are spelled, but it does matter being consistent in the choice, which is why we need style guide rules about it and a source for making the decision we do. By adopting the Oxford way, we gain four main benefits:

1. It provides a precise reason and source for the decision to write words the way we do, without any wishy-washy and debatable explanations (as was in the old style guide, which I wrote).
2. It's definable in metadata to a more precise level: lang="en-GB-oxendict".
3. It will be a measure easier for future Txp authors/editors who come from a significant part of the English-speaking world that uses the same conventions. (And there's the fact Dean Allen, Txp's progenitor, is Canadian, and Canada uses -ize.) And somewhat related...
4. Being a compromise across GB and US conventions, it effectively normalizes the effort to where one side of writers/editors doesn't have the upper hand on the other.

I realize you are all British, so this might sound like hogwash to you, but I rather like the idea, considering how English around the world is used so differently, and even evolving in a given region — like Britain.

As for fixing docs so far, that's an easy matter of just changing all -ise instances of words with find/replace or just doing it when they are found.

Let me know what you think because I'm in the process of updating the editorial style guide.

Sorry for the essay.

[petecooper]

A solid proposal. +1.

[wion]

Here's how that would read in the style guide... http://docs.textpattern.io/brand/editorial-style-guidelines#lang

(Ignore the rest of the doc, which is a flux of change and transformation.)

[philwareham]

I'm also fine with your proposal. Good to have an absolute guideline for copy writing - so please proceed.

I will amend the lang value in head later.

[wion]

122

[wion]

NTS: Add Terminology section to ESG and add note about 'directory' over 'folder'.

[wion]

Wow, issue opened more than 5 years ago. / hangs head / Time to take care of this one.

I've updated the head post to reflect new status. I'm starting this now and will not take on new tasks until it's done.

[petecooper]

issue opened more than 5 years ago

Ah, don't even worry about that. There are some stinkers on https://github.com/textpattern/textpattern/ that date back to 2009.