sheppy

Writer. Programmer. Geek. Dad. Keeper of strong opinions about grammar. All hail the Oxford Comma! All hail the Oxford Comma!

Nov 132017
 

Last week, I wrote about the results of our “thin pages” (that is, pages too short to be properly cataloged by search engines) SEO experiment, in which we found that while there appear to be gains in some cases when improving the pages considered to be too short, there was too much uncertainty and too few cases in which gains seemed to occur at all, to justify making a full-fledged effort to fix every thin page on MDN.

However, we do want to try to avoid thin pages going forward! Having content that people can actually find is obviously important. In addition, we encourage contributors working on articles for other reasons who find that they’re too short to go ahead and update them.

I’ve already updated our meta-documentation (that is, our documentation about writing documentation) to incorporate most of the recommendations for avoiding thin content. These changes are primarily in the writing style guide. I’ve also written the initial portions of a separate guide to writing for SEO on MDN.

For fun, let’s review the basics here today!

What’s a thin page?

A thin page is a page that’s too short for search engines to properly catalog and differentiate from other pages. Pages that are shorter than 250-300 words of content text do not provide enough context for search algorithms to reliably comprehend what the article is about, which means the page winds up not in the right place in search results.

For the purposes of computing the length of an article, the article’s length is the number of words of body content—that is, content that isn’t in headers, footers, sidebars, or similar constructs—plus the number of words located in alt text on <img> elements.

How to avoid thin pages

These tips are taken straight from the guidelines on MDN:

  • Keep an eye on the convenient word counter located in the top-right corner of the editor’s toolbar on MDN.
  • Obviously, if the article is a stub, or is missing material, add it. We try to avoid outright “stub” pages on MDN, although they do exist, but there are plenty of pages that are missing large portions of their content while not technically being a “stub.”
  • Generally review the page to ensure that it’s structured properly for the type of page it is. Be sure every section that it should have is present and has appropriate content.
  • Make sure every section is complete and up-to-date, with no information missing. Are all parameters listed and explained?
  • Be sure everything is fully fleshed-out. It’s easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Known restrictions that the reader might need to know about?
  • There should be examples covering all parameters or at least common sets of parameters. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don’t skimp on the details and the handling of errors in examples; readers will copy and paste your example to use in their own projects, and your code will wind up used on production sites! See Code examples and our Code sample guidelines for more useful information.
  • If there are particularly common use cases for the feature being described, talk about them! Instead of assuming the reader will figure out that the method being documented can be used to solve a common development problem, actually add a section with an example and text explaining how the example works.
  • Include proper alt text on all images and diagrams; this text counts, as do captions on tables and other figures.
  • Do not descend into adding repetitive, unhelpful material or blobs of keywords, in an attempt to improve the page’s size and search ranking. This does more harm than good, both to content readability and to our search results.

Reviewing the above guidelines and suggestions (some of which are admittedly pretty obvious) when confronted with pages that are just too short may help kick-start your creativity so you can write the needed material to ensure that MDN’s content drifts to the top of the turbid sea of web documentation and other content to be found on the Internet.

 Posted by at 12:50 PM
Nov 082017
 

The MDN team has been working on a number of experiments designed to make decisions around prioritization of various forms of SEO problems we should strive to resolve. In this document, we will examine the results of our first such experiment, the “Thin Pages” experiment.

The goal of this experiment was to select a number of pages on MDN which are considered “thin”—that is, too short to be usefully analyzed—and update them using guidelines provided by our SEO contractor.

Once the changes were made and a suitable time had passed, we re-evaluated the pages’ statistics to determine whether or not the changes had an appreciable effect. With that information in hand, we then made a determination as to whether or not prioritizing this work makes sense.

The content updates

We selected 20 pages, choosing from across the /Web and /Learn areas of MDN and across the spectrum of usage levels. Some pages had little to no traffic at the outset, while others were heavily trafficked. Then, I went through these pages and updated them substantially, adding new content and modernizing their layouts in order to bring them up to a more useful size.

The changes were mostly common-sense ones:

  • Pages that aren’t necessary were deleted (as it turns out, none of the pages we selected were in this category).
  • Ensuring each page had all of the sections they’re meant to have.
  • Ensuring that every aspect of the topic is covered fully.
  • Ensuring that examples are included and cover an appropriate set of cases.
  • Ensuring that all examples include complete explanations of what they’re doing and how they work.
  • Ensuring that pages include not only the standard tags, but additional tags that may add useful keywords to the page.
  • Fleshing out ideas that aren’t fully covered.

The pages we chose to update are:

The results

After making the changes we were able to make in a reasonable amount of time, we then allowed the pages some time to percolate through Google’s crawler and such. Then we re-measured the impression and click counts, and the results were not quite what we expected.

First, of all the pages involved, only a few actually got any search traffic at all. The following pages were not seen by users searching on Google at all during either/or the starting or ending analysis:

The remaining pages did generally see measurable gains, some of them quite high, but none are clearly outside the range of growth expected giving MDN’s ongoing growth:

June 1-30 Sept. 24 – Oct. 23
Page URL Clicks Impressions Clicks Impressions Clicks Chg. % Impressions Chg. %
https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries 15 112 111 2600 640.00% 2221.43%
https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translateZ 1789 6331 1866 9004 4.30% 42.22%
https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements 3151 60793 4729 100457 50.08% 65.24%

This is unfortunately not a very large data set, but we can draw some crude results from it. We’ll also continue to watch these pages over the next few months to see if there’s any further change.

The number of impressions went up, in some cases dramatically. But there’s just not enough here to be sure this was related to the thin page revisions or related to other factors, such as the large-scale improvements to the HTML docs recently made.

Uncertainties

There are, as mentioned already, some uncertainties around these results:

  • The number of pages that had useful results was smaller than we would have preferred.
  • We had substantial overall site growth during the same time period, and certain areas of the site were heavily overhauled. Both of these facts may have impacted the results.
  • We only gave the pages a couple of months after making the changes before measuring the results. We were advised that six months is a more helpful time period to monitor (so we’ll look again in a few months).

Decisions

After reviewing these results, and weighing the lack of solid data at this stage, we did come to some initial conclusions, which are open to review if the numbers change going forward:

  1. We won’t launch a full-scale formal project around fixing thin pages. It’s just not worth it given the dodginess of the numbers we have thus far.
  2. We will, however, update the meta-documentation to incorporate the recommendations around thin pages.That means providing advice about the kinds of content to include, reminding people to be thorough, reminding writers to include plenty of samples that cover a variety of use cases and situations, and so forth. We will also add a new “SEO” area to the meta docs that covers these recommendations more explicitly in terms of the SEO impact.
  3. We will check these numbers again in a couple of months to see if there’s been further improvement. The recommendation was to wait six months for results, but we did not have that kind of time.

Discussion?

For discussion of this experiment, and of the work updating MDN that will come from it, I encourage you to follow-up or comment in this thread on the Mozilla Discourse site.

 Posted by at 11:22 AM
Oct 152017
 

Over the last 15-20 years, there’s been a disturbing trend in filmmaking. No, I don’t mean superhero sequels. I’m cool with that (mostly; I’m talking to you, moody, conflicted take on Superman). I mean shaky cinematography.

Obviously, cinematography can be used to create a mood or set the emotional tone of a scene in a film. Used properly, techniques in camera work can heighten the sense of urgency in a scene, and some degree of camera shake can give a sense of being along for the ride, or that feeling of watching a documentary rather than a work of fiction.

The problem is when the camera bounces around so much that it makes the viewer seasick, or causes headaches. Even this wouldn’t be too bad in limited doses. What’s really bad is when entire movies are filmed with cameras handled as if operated by people who just quit a massive coffee habit and are going through caffeine withdrawal.

I’m writing this while trying to watch “The Bourne Supremacy.” I started writing because the camera work in this film is so unsteady that I can only watch a few moments at a time for large stretches of the movie. What’s the point to making a movie that’s so hard to watch?

Of all the filmmaking techniques available, this is, I think, the most annoying even in limited amounts. Can this trend please finally stop? I’d rather have excessive lens flares. Really.

 Posted by at 3:26 PM
Sep 192017
 

Due to the size and arrangement of the rooms in our new house, we realized we need a way to communicate room-to-room that didn’t involve shouting at each other. Since we don’t all have a phone on us all the time, we decided an intercom is just the ticket.

After experimenting a while with using WebRTC to make intercom software for tablets we could wall-mount, we decided to get a limited number of Nucleus intercom and see if we like them. So we now have then on place, and while they’re pretty nifty, I have several frustrations and disappointments. I’ll share a few here.

  • There’s an app that lets you call intercoms from mobile devices, but they can’t call each other.
  • While there’s a “broadcast all” button to make an announcement through all intercom units, you can’t include mobile devices in the broadcast. These two items preclude using spare tablets as extra intercoms.
  • More frustratingly, there’s no way to broadcast to a single intercom. I want to be able to announce to my daughter when her door is closed and she’s not yet fully awake that she’s running late for school.
  • It’s nifty that you can have remote intercom stations located on other networks (at Grandma’s house, for example), but if you don’t have any, the “Remote” tab in the main UI shouldn’t exist. It’s too easy to accidentally swipe your main station list away, and this could confuse younger (or older) household members. Same goes if there are no local stations, for that matter.
  • You can’t customize the ringtone.
  • You should be able to control the volume level of calls, engines, and Alex’s voice individually.
  • Each station is represented by a name and a small photo. It needs a way to set station photos to pictures taken on other devices; using the built-in camera for this is an exercise in frustration resulting in hideous icons.
  • Each station on the menu of intercoms has a big box but you have to tap a much smaller area to start a call. Instead, the whole thing should start a video call, with a smaller button to do audio instead.
  • In addition to the above, a preference for whether audio or video calls are the default would be nice to have.
  • There’s no way in the UI to answer a video call request with “I’ll talk but audio only.”
  • I’d love to have more ability to customize the display. Show family calendars and chore lists. Stuff like that. Basically, it’d be awesome to run apps or even little applets on it! This alone could turn this into a much better device.
  • I wish I could leave messages for viewing or listening to at a later time.
  • It uses WebRTC and other standards but has enough opaque, proprietary stuff to prevent me from experimenting with it or connecting from non-Nucleus code.
  • It supports streaming music, but has speakers woefully inadequate for the task, with no jack for adding external speakers or support for using Bluetooth to connect to speakers or headphones. The sound is bad enough that when Sarah hears it she makes me she it off because the run, weak audio makes her cringe.

There’s more, but we get into more nitpicky stuff at this point. Suffice it to say, the Nucleus intercom is avoid idea and shows prone, but needs to evolve quickly.

I haven’t decided yet if we’ll keep them. We have a couple more months to decide if we can accept the limitations before we run out of free return time.

 Posted by at 6:40 AM
May 182017
 

My health continues to be an adventure. My neuropathy continues to worsen steadily; I no longer have any significant sensation in many of my toes, and my feet are always in a state of “pins and needles” style numbness. My legs are almost always tingling so hard they burn, or feel like they’re being squeezed in a giant fist, or both. The result is that I have some issues with my feet not always doing exactly what I expect them to be doing, and I don’t usually know exactly where they are.

For example, I have voluntarily stopped driving for the most part, because much of the time, sensation in my feet is so bad that I can’t always tell whether my feet are in the right places. A few times, I’ve found myself pressing the gas and brake pedals together because I didn’t realize my foot was too far to the left.

I also trip on things a lot more than I used to, since my feet wander a bit without my realizing it. On January 2, I tripped over a chair in my office while carrying an old CRT monitor to store it in my supply cabinet. I went down hard on my left knee and landed on the monitor I was carrying, taking it squarely to my chest. My chest was okay, just a little sore, but my knee was badly injured. The swelling was pretty brutal, and it is still trying to finish healing up more than four months later.

Given the increased problems with my leg pain, my neurologist recently had an MRI performed on my lumbar (lower) spine. An instance of severe nerve root compression was found which is possibly contributing to my pain and numbness in my legs. We are working to schedule for them to attempt to inject medication at that location to try to reduce the swelling that’s causing the compression. If successful, that could help temporarily relieve some of my symptoms.

But the neuropathic pain in my neck and shoulders continues as well. There is some discussion of possibly once again looking at using a neurostimulator implant to try to neutralize the pain signals that are being falsely generated. Apparently I’m once again eligible for this after a brief period where my symptoms shifted outside the range of those which are considered appropriate for that type of therapy.

In addition to the neurological issues, I am in the process of scheduling a procedure to repair some vascular leaks in my left leg, which may be responsible for some swelling there that could be in part responsible for some of my leg trouble (although that is increasingly unlikely given other information that’s come to light since we started scheduling that work).

Then you can top all that off with the side effects of all the meds I’m taking. I take at least six medications which have the side effect of “drowsiness” or “fatigue” or “sleepiness.” As a result, I live in a fog most of the time. Mornings and early afternoons are especially difficult. Just keeping awake is a challenge. Being attentive and getting things written is a battle. I make progress, but slowly. Most of my work happens in the afternoons and evenings, squeezed into the time between my meds easing up enough for me to think more clearly and alertly, and time for my family to get together for dinner and other evening activities together.

Balancing work, play, and personal obligations when you have this many medical issues at play is a big job. It’s also exhausting in and of itself. Add the exhaustion and fatigue that come from the pain and the meds, and being me is an adventure indeed.

I appreciate the patience and the help of my coworkers and colleagues more than I can begin to say. Each and every one of you is awesome. I know that my unpredictable work schedule (between having to take breaks because of my pain and the vast number of appointments I have to go to) causes headaches for everyone. But the team has generally adapted to cope with my situation, and that above all else is something I’m incredibly grateful for. It makes my daily agony more bearable. Thank you. Thank you. Thank you.

Thank you.

 Posted by at 11:15 AM
May 122017
 

I’ve been writing developer documentation for 20 years now, 11 of those years at Mozilla. For most of those years, documentation work was largely unmanaged. That is to say, we had management, and we had goals, but how we reached those goals was entirely up to us. This worked well for me in particular. My brain is like a simple maze bot in some respects, following all the left turns until it reaches a dead end, then backing up to where it made the last turn and taking the next path to the right, and repeating until the goal has been reached.

This is how I wrote for a good 14 or 15 years of my career. I’d start writing about a topic, linking to APIs, functions, other guides and tutorials, and so forth along the way—whether they already existed or not. Then I’d go back through the page and click the first link on the page I just created, and I’d make sure that that page was solid. Any material on that page that needed to be fixed for my new work to be 100% understood, I’d update. If there were any broken links, I’d fix them, creating and writing new pages as needed, and so forth.

How my mind wants to do it

Let’s imagine that the standards gurus have spoken and have decided to add to a new <dial> element to HTML, providing support for creating knobs and speedometer-style feedback displays. My job is to document this element.

I start by creating the main article in the HTML reference for <dial>, and I write that material, starting with a summary (which may include references to <progress>, <input>, and other elements and pages). It may also include links to articles I plan to create, such as “Using dial elements” and “Displaying information in HTML” as well as articles on forms.

As I continue, I may wind up with links to subpages which need to be created; I’ll also wind up with a link to the documentation for the HTMLDialElement interface, which obviously hasn’t been written yet. I also will have links to subpages of that, as well as perhaps for other elements’ attributes and methods.

Having finished the document for <dial>, I save it, review it and clean it up, then I start following all the links on the page. Any links that take me to a page that needs to be written, I write it. Any links that take me to a page that needs content added because of the new element, I expand them. Any links that take me to a page that is just horribly unusably bad, I update or rewrite as needed. And I continue to follow those left-hand turns, writing or updating article after article, until eventually I wind up back where I started.

If one of those pages is missing an example, odds are good it’ll be hard to resist creating one, although if it will take more than a few minutes, this is where I’m likely to reluctantly flag it for someone else to do later, unless it’s really interesting and I am just that intrigued.

By the time I’m done documenting <dial>, I may also have updated badly out of date documentation for three other elements and their interfaces, written pages about how to decide on the best way to represent your data, added documentation for another undocumented element that has nothing to do with anything but it was a dead link I saw along the way, updated another element’s documentation because that page was where I happened to go to look at the correct way to structure something, and I saw it had layout problems…

You get the idea.

How I have to do it now

Unfortunately, I can’t realistically do that anymore. We have adopted a system of sprints with planned work for each sprint. Failing to complete the work in the expected amount of time tends to get you dirty looks from more and more people the longer it goes on. Even though I’m getting a ton accomplished, it doesn’t count if it’s not on the sprint plan.

So I try to force myself to work on only the stuff directly related to the sprint we’re doing. But sometimes the line is hard to find. If I add documentation for an interface, but the documentation for its parent interface is terrible, it seems to me that updating that parent interface is a fairly obvious part of my job for the sprint. But it wasn’t budgeted into the time available, so if I do it, I’m not going to finish in time.

The conundrum

That leaves me in a bind: do strictly what I’m supposed to do, leaving behind docs that are only partly usable, or follow at least some of those links into pages that need help before the new content is truly usable and “complete,” but risk missing my expected schedule.

I almost always choose the latter, going in knowing I’m going to be late because of it. I try to control my tendency to keep making left turns, but sometimes I lose myself in the work and write stuff I am not expected to be doing right now.

Worse, though, is that the effort of restraining myself to just writing what’s expected is unnatural to me. My brain rebels a bit, and I’m quite sure my overall throughput is somewhat lower because of it. As a result: a less enjoyable writing experience for me, less overall content created, and unmet goals.

I wonder, sometimes, how my work results would look if I were able to cut loose and just go again. I know I have other issues slowing me down (see my earlier blog post Peripheral neuropathy and me), but I can’t help wondering if I could be more productive by working how I think, instead of doing what doesn’t come naturally: work on a single thing from A to Z without any deviation at all for any reason.

 Posted by at 10:30 AM
Apr 032017
 

As of today—April 3, 2017—I’ve been working as a Mozilla staffer for 11 years. Eleven years of documenting the open Web, as well as, at times, certain aspects of the guts of Firefox itself. Eleven years. Wow. I wrote in some detail last year about my history at Mozilla, so I won’t repeat the story here.

I think 2017 is going to be a phenomenal year for the MDN team. We continue to drive forward on making open web documentation that can reach every web developer regardless of skill level. I’m still so excited to be a part of it all!

A little fox that Sophie got me

Last night, my eleven-year-old daughter (born about 10 months before I joined Mozilla) brought home this fox beanie plush for me. I don’t know what prompted her to get it—I don’t think she’s aware of the timing—but I love it! It may or may not actually be a red panda, but it has a very Firefox look to it, and that’s good enough for me.

 Posted by at 7:12 AM