Friday, December 30, 2016

On the Contrary, It's a Great Idea

I read this thread called "Is it overkill to follow style-guides for technical writing?" the other day and it made me think, "Why yes, a style guide is a great idea!" Too many pages of documentation I see do not follow a style guide:


There is a lot going on in that screenshot:
  1. the choice to imply that a machine can remember something is not a choice I would make. I do not think Firefox actually remembers a login. I think a web browser on a device stores a login or saves a login. To me, only humans remember.
  2. the choice to structure the purpose statements is inconsistent. The sentence that begins "While in" does not use the word "you" where as the sentence that is under the first screenshot uses the word "you" twice.
  3. the choice to use the term "deselect" is both awkward and inconsistent with other pages. A brief search on other  pages in this documentation indicates that sometimes "clear" is being used, but on this page, a different word was selected.
  4. the choice of color for rectangles around an area of a screenshot is inconsistent. In the top screenshot, a green rectangle is used while in the second and third screenshot, a red rectangle is used. What is the purpose of the two different colors? What does it mean to the user? Why is there neither a red nor a green rectangle around the actual text being described in the purpose statement on the screenshot in step 2?
  5. the choice to bold user interface elements - buttons and sections - is inconsistent. While specific references to sections and check boxes are bold elsewhere on this page, the text of a specific notification is not. I presume that bold was used for the sections and check boxes because they are on the screen. However, the notification is also on the screen.
I wrote those points after looking at the above after only a couple of minutes. Imagine what a full-time editor would do with it!

No comments: