Half-Elf on Tech

Thoughts From a Professional Lesbian

Tag: writing

  • Context is Everything

    Context is Everything

    In the uptick of automated scans, we come to the place where we realize it’s not just the quality of content that matters in our success, but the context.

    Context in Content

    When you write content, the body of your work depends on the literary context of the words. Writing about technology on a non-tech site requires you to step back and explain the tech in a little more detail than you normally might. For example, if I were to post about shortcodes here, I would not bother to give you the history of what they were or why they’re used. I would trust you to know those things, or be ready and able to research them.

    By contrast, when writing about code used on a journalism site, and explaining we had a nifty new shortcode to do a thing, I absolutely would take time to explain. I would not expect my readers there, who care about the goings on of television, to understand about the weirdness of a shortcode. At the same time, I may not need to delve into details quite so much. I could just say “We have a new, faster way to add whatever, which will make it easier for us to report on X.”

    In short, I consider the audience when I write the content. I write contextually.

    Context in Code

    When it comes to writing code, there is a similar mindset. The code should make sense contextually and be consistent. If you’re using underscores for filenames, always use underscores, just to give one example. But this goes further than having a same prefix or formatting (tabs or spaces, eh?). It also means that when data is processed, it should be done so contextually.

    If you have a form, and you allow people to enter data to send to you, and that data is saved to a database, you have to sanitize the data. That’s a no-brainer for every developer worth the time of day. Never save unsanitized data, and sanitize as early as possible to minimize the possible damage. But deciding how best to sanitize can be tricky. PHP comes with stripslashes() for example, however consider that PHP says this:

    An example use of stripslashes() is when the PHP directive magic_quotes_gpc is on (it was on by default before PHP 5.4), and you aren’t inserting this data into a place (such as a database) that requires escaping. For example, if you’re simply outputting data straight from an HTML form.

    In other words, you shouldn’t use that to save data. Thankfully in WordPress (and Drupal and everything else) there are many ways to sanitize your inputted data based on … you guessed it, context. You don’t sanitize a URL as a plain text field, and you don’t sanitize an HTML form as a filename.

    When you write your code, sanitize, validate, and escape it contextually based on what it is.

    The Bottom Line: Context Matters

    This is the thing that automated checkers can’t quite do. They don’t know what the input is supposed to be unless you tell them, so they can’t verify your sanitization as well as a human can. Even grammar checkers can’t tell you when it’s okay to use slang and when it’s not, when you’re trying to explain a new concept.

    In the end? We need humans.

  • Where Did Underline Go?

    Where Did Underline Go?

    As of WordPress 4.7, the visual editor no longer has a button for underline. There were a lot of reasons for this, but primary are two:

    1. Space is not limitless.
    2. Underlining looks like links.

    Naturally someone complained that we were breaking style guides:

    When referencing a source of information it is correct form to underline the title of the source.

    They happen to be wrong. Let me explain.

    The Web Is Not Print

    We use double spaces to indicate the end of a sentence in printed works. We don’t on the Internet. It took me a long time to get used to that, and if you look back on my older posts, you’d see it all over the place. The point here is that we know you don’t use the same punctuation and style you might use online as you do on paper.

    I look to the grandpappy of web, Jakob Nielsen, for some backup here. Your writing style for the web is different from print. A lot different. In Writing Style for Print vs. Web he says:

    In linear media — such as print and TV — people expect you to construct their experience for them. Readers are willing to follow the author’s lead.

    In non-linear hypertext, the rules reverse. Users want to construct their own experience by piecing together content from multiple sources, emphasizing their desires in the current moment. People arrive at a website with a goal in mind, and they are ruthless in pursuing their own interest and in rejecting whatever the site is trying to push. Banner blindness is only the most extreme manifestation of this selfishness.

    But that talks about the way we write and not the design of what it looks like. Web and print design are wildly different too. For newspapers, you have to consider the width of the columns. If you’ve never taken a journalism course, there’s as much about layouts as there is about writing a solid lede.

    Good Writing Has Rules

    I’m a huge fan of Strunk & White’s The Elements of Style. My wife has a copy and, when we met, she found my grammar to be deplorable and used to wave it at me a lot. Having read it multiple times (yes, I do re-read it) I’ve found my communication skills have been catapulted because of the directions. People ask me why I’m a good speaker and the answer is because I’m a good writer.

    One of the lessons from Strunk & White is to use the active voice, for example, which is something Nielsen points out as well. You need to engage your readers. You need to bring them on a journey and make it theirs as much as yours. To do that, you need to understand the rules of the language in which you’re writing.

    Content Must Not Confuse By Context

    Going back to the heart of the matter, why is it okay that WordPress killed the underline button? It was confusing.

    Originally we underlined links because it was easy and being consistent about a display reduced the chances for misunderstandings. Why were they underlined and blue? I actually have no idea. I looked it up but was unable to find a solid answer. My theory was that blue would stand out against the standard grey background as well as the black words so everyone knew what it was for. Similarly, on a monochrome screen, which was very common in the day, an underline would stand out (as it happens, Sir Tim Berners-Lee picked blue totally by happenstance).

    Why underline and not bold or italics? My guess is that since underlining is not actually standard practice for writers, it was a safe grab. Otto pointed out that old-old systems always had underlines, but not always italics or bold, so that weighed heavily into the decision as well, clearly.

    In a word, it wasn’t confusing. It was consistent.

    It’s Actually Italics

    Did you double take when I said underlining wasn’t standard practice? Surprise! Let me appeal to Misters Strunk & White on a few matters of form:

    Titles. For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial A or The from titles when you place the possessive before them.

    The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities;Dickens’s Tale of Two Cities.

    Notice the direction to use italics? The talk of a manuscript is in reference to the fact that most people wrote manuscripts by hand or on typewriters that didn’t have italics. I remember having to type a line, and then backspace to add in the underline manually. Have you ever tried to write italics manually? It’s not easy!

    The web is not handwritten. Computers in 2016 can handle italics.

    And it’s not just Strunk & White. Harvard’s documentation on citation doesn’t recommend underlining at all. The MLA (Modern Language Association) says, as of this year, to use italics for large works like books and magazines, but quotes for short ones in titles. The Chicago Style Guide reads the same.

    Use Italics, Not Underline

    If you skip the whole post, let me make this simple for you: The title of a source should be italicized.

  • Clear Communication

    Clear Communication

    “Your guidelines should be so clear as to not permit so much wriggle room,” he said.

    I started at my screen for a moment, feeling my neck heat up with the sheer arrogance of his implication. Besides the fact that I did spend quite a bit of time trying to make them as transparent and clear as possible, it’s a known impossibility.

    Anyone who’s ever written anything knows that it will always be interpreted by someone in an unintended way. Have a look at the US Constitution, which we’re still arguing about to this day. It’s categorically impossible to write anything in a way that will be perfectly understood by everyone who reads it, past, present, or future.

    Let’s step back though and think about what the post of such a statement might be.

    Everything we write for the purposes of education should be as clear as possible, in order to minimize confusion. We can all agree on that. Guidelines, documentation, how-tos, and the like are all for education. When you write a story, a novel for example, you don’t need to write for clarity but for a different purpose. I won’t get into that today.

    To that end, his statement was correct. We should write our guidelines not to permit wriggle room.

    However when we consider what the guidelines were, and please note they are indeed guidelines and rules, we hit a different situation. Guidelines are meant to direct people into doing what is expected of them. Some can be as clear as “Don’t steal” but others have to be a little more broad like “Don’t hurt people intentionally.” That’s a very big statement, and while it’s certainly a good guideline for any group, enforcing it without specific examples is always going to be problematic.

    The difference between rules and guidelines is that rules can be clear, while guidelines must allow for interpretation. And even with rules, it’s categorically impossible to write them in a way that will never ever be misconstrued.

    So what do we do?

    We write things as clearly as possible. We state, upfront, that the guidelines have an intended purpose and what that is. We remind people that the guidelines cannot cover each and every possible permutation of events. We admit that some of these will be up to the discretion of the people enforcing them. We write a disclaimer that we are human and we are mortal.

    We do our best. And if someone says “These could be better” we ask “How? Please help.”

    I can tell you from experience, less than 1% of people who complain about your guidelines will help, though.

    Comments on this post have been disabled.