Session 02: Designing the Solution

Session 02: Designing the Solution

Session 01: Kick-off
Session 03: Drafting the Guide

Hey there! Welcome to this session of the How To Make Guides project where I am creating a guide to standardize guide making based on best practices. In the previous session, I kicked off the project by reviewing the history; identifying the needs, goal, scope, and objectives; and, established a production plan. In this session, I’m going to design the solution based off the resource materials. I do not have a SME at this time so I’m just going to use the guide making sources I found from University of Bath.

Let’s begin by looking back at the project specs:


The goal of this project is to create a guide that will instruct users on how to create how-to guides.

The pass/fail objectives for this project are:

  1. The project followed Cryptiquest Project Management guidelines
  2. The Production Phase was finished by January 31st, 2020.
  3. The product is available for free in digital and print form.
  4. The product exemplifies the rules it teaches.
  5. The product can be easily updated (where easily updated is defined less than a day to simple content update and post) based on user feedback.

And the ideal solution was defined as follows:

“…a how-to guide that walks the user through the steps for creating a guide, including logistical information for formats (perhaps best letter spacing and the like), and includes one or more templates for various guide sections.”


I have four references that I will pull research from:

  1. Cryptiquest’s Project Management Guidelines
  2. University of Bath’s Creating a ‘How’ to Guide
  3. The Indie Game Report’s Rulebook Cookbook: Recipe for Success
  4. Mark Schenker’s Readability vs. legibility: How to create user-friendly web typography (via 99designs)

Each of these references are fragments that will add to the guide. The PM guidelines from Cryptiquest (CQ) will provide the project management portion of the guide. University of Bath (Bath) and The Indie Game Report’s (TIGR) content will help supplement the information architecture and along with Schenker’s article, will also provide best practices for visual usability.

I was (and still am) concerned about having a subject matter expert to certify the validity of the information with “theory”. I’m still lacking the theory side of things. I trust the reference materials enough to build the guide. It may be easier to draft the guide and ask for subject matter once it’s complete. I’m not concerned enough about this to hold up production.

Thoughts on the Guide

Off the top of my head, I envision that the guide will instruct the building of a guide as a project – following the project guidelines set forth by CQ. But the guide itself will be set up as a guide – so it might require a “materials needed” section before the step-by-step project planning process, for instance. The different phases of the project planning portion – especially production – will be customized to creating guides as advised by Bath, TIGR, and Schenker.

So, in essence, it’s a project management doc tailored for creating guide products wrapped in a guide format. Once this project is complete, I will take the CQ Project Management Guidelines and make them into an official guide for the public.

Gathering Information

I was originally going to dump all the content here that I found useful from the references but it felt kind of slimy to do so. So instead, I’ve created an offline source of all the related content. Also, I discovered that the TIGR article goes way more in depth than I originally realized as there are pages that explore each section of the rulebook recipe complete with comparing/contrasting real-world examples.

What is the difference between a how-to guide as prescribed by Bath and a game rulebook as prescribed by TIGR?

How-to GuideGame Rulebook
TitleTitle
-no equivalent-Thematic Introduction
SummaryGame Overview
-no equivalent-Component List
Stages with HeadingsSetup > Gameplay > Endgame
Optional Call-to-ActionOptional Extras

I think that covers it. The reasons behind the discrepancies are understandable. I’m going to try to analyze each of these with CQ guides in mind. Obviously, if the guide I’m creating is for a game then the game rulebook anatomy would apply so I’m only going to consider upcoming how-to guides for this exercise.

Title is obviously necessary. The only way I see that Cryptiquest guides might need a thematic introduction is if the brand (which will be created in the future) lends itself to a theme (e.g. if the guides are touted as magical tomes, etc.). But that wouldn’t come into play until after the branding has been established.

The summary is necessary and is very similar to the game overview. A component list, while not necessary for the upcoming guides, might be a good place to write down the things users need before creating the guide (if anything).

Stages with Headings and the game rulebook equivalent are necessary as are the optional sections at the end.

Guide Outline

  1. Title
  2. Version
  3. Summary
  4. Requirements (if any)
  5. Stages
    1. Planning
    2. Production
    3. Review
    4. Implementation
    5. Launch
    6. Retrospective
    7. Close
  6. Appendix

I feel confident about the layout of the content and how to approach the build. Next I’ll explore the presentation of the guide.

When it comes to guides, readability (how easy a document reads; sentence structure and word usage) and legibility (how easy a document is to read; fonts and text properties) are especially important to get right. The goal is to instruct and give clear directions and poor readability or legibility hinder that goal.

The Schenker reference addresses digital, the context is fairly universal. The article was chosen because of how convenient it defines the anatomy of readability and legibility. I’ll list these out and decide parameters for the guide. In addition, there are some tips from the article that I’ll categorize at the end.

  • Line length. In reference to text blocks, the fewer words per line the easier it is for humans to read text – to a point. Too few words per line and it causes a new chore of scrolling and adds a weird bonus of the brain trying to recognize patterns. A nice rule is to keep it between 7 – 13 words per line (on average).
  • Kerning. The distance between two characters. Certain fonts will have kerning data embedded within it but they need to be set using CSS otherwise it will be left up to the browser whether to apply it or not. If this still isn’t good enough, certain pairings will have to be manually styled using <span> tags which – due to the laborious setup/maintenance involved, should be avoided at all costs.
  • Tracking. The distance all characters are to each other. Too close and it becomes difficult to discern certain character pairings, too far away and it can become confusing between what are words. Most fonts are calibrated for this already but I think this is something to play with once the guide is created.
  • Alignment. I’m personally in love with justified text. It just makes everything nice and neat looking. But it’s not necessarily better to read. It stretches the space between words and can make some lines distracting. Left-aligned text is your best bet.
  • Leading. The vertical space between lines. By default, I always feel lines are too close together. Giving them a little more breathing room is a relief on the reader, increasing readability. But you can’t go too far or else it’s confusing. This will have to be tweaked once the guide is finished.
  • Point Size. It is recommended that the font is between 15 and 25 pixels (which coincides with the suggested “larger than 10pt” later in the article). I’m a fan of larger font. Squeezing font size to get information above the fold doesn’t matter when you’re making a guide. However, too big of a font can be just as distracting. I think an 18 – 20px size font is good.
  • Font Style. This might be obvious but the more stylized and busy a font is the harder it will be to interpret the content. Fonts used for copy should be as “normal” as possible. That doesn’t mean it has to be boring. Normal fonts have personalities of their own. But for a guide, the only thing that matters is legibility – personality is secondary.
  • x-height. The height of the lowercase letter “x” (which represents the height of lowercase letters) should be tall but clearly lower than the height of capital letters. This can’t be controlled with styles and is purely dependent on font choice.
  • Serif or sans serif. It really doesn’t matter. A poorly legible serif font will be just as bad as a poorly legible sans serif font. The main difference is personality – serif fonts seem more traditional and professional where as sans serif fonts can be seen as more modern and informal. For the guide, I will stick with a serif font but I might use a sans serif font for headers or call outs. Not sure.
  • Character shape. I honestly don’t know why this is called out as a property to keep in mind – or at least not without mentioning line width. Again, this is one of those things that can’t be controlled with styles (aside from adjusting font weight). I will be looking for a font that has good contrast between positive and negative space.
  • Voice. According to the Schenker, the words chosen should aim for a 6th – 8th grade reading level by using simple words, avoiding jargon, using conventional language. Within the article are links to readability tools such as this free Automatic Readability Checker.
  • Layout. Design for mobile-first (one column) then move content to second columns for wider screens sensibly. Using images (as barriers) and smaller paragraphs can help chunk content into manageable sizes. According to Bath, section headers and numbered steps should also be used (this is obvious but the tips also go into how to write effective headers, etc.).
  • Color. The contrast between the foreground and background has to be fairly high. I use the WebAIM tool to check my colors to ensure proper contrast. In addition, the background should not be patterned or an image unless proper steps are taken to ensure legibility (stroke, wash-out, drop shadow, etc.).

(As I was creating this I am reminded that I should craft style guides for each brand. I’ll add a note about that to the Action Items.)

For the guide, I think I will sort all of those points into sections that make sense. Instead of readability and legibility, it might be based on what the user can control: font choice, typography, layout, voice, colors.

There is a MAJOR step missing here: design for mobile device. It’s all well and good to talk about breaking up content with images until you see that it ultimately just becomes one column in mobile. In fact, this should 100% be designed for mobile first and then things can be moved into a second column as it makes sense. I’ll add that to the bullets (which will eventually make this paragraph look weird in hindsight).

I think that’s good for now. I won’t work on the fonts or colors or anything like that until the content is ready but I will keep the voice in mind.

With the content and presentation figured out, there is the matter of hosting and maintaining. While the guide can live on the projects site, there is a matter of versioning which is a Cryptiquest objective that has yet to be implemented.

Versioning

Looking through past projects, versioning was identified as an important objective but the process for versioning was pushed until the creation of guides. It seems that this is a fitting place to figure this out.

The idea I had for versioning was that there would be a two-digit three decimal code: 00.00.00. The code stands for:

Edition | Major Update | Minor Update

The code parts would be defined as follows:

  1. Edition: A complete rewrite from the previous version
  2. Major Update: A new concept, non-conceptual revamp, or partial modification.
  3. Minor Update: A modification or addition which does not require review support.

Had I been versioning the project standards guidelines, the current version would probably look like 00.02.02. As it stands, I haven’t been tracking the versions so it’s 00.00.00.

Once I do start versioning though, there will be a need to log the old versions. The only way that I know to create/maintain a public log with the current technology is to manually do it. That sounds like a nightmare.

Let’s explore the concept though. I suppose there could be a page of archives. On that page there are headings for each guide that’s being logged. Under each heading, there is a list of versions. Each version is a link to a page for that guide. The archive would look something like this:

Project Management Guidelines

  • 00.00.01 (First Draft)
  • 00.01.00 (First Publish)
    • 00.00.01
  • 00.02.00 (Review and Close Update)
    • 00.02.01
    • 00.02.02
  • 01.00.00 (Guide Update)
    • 01.00.01
    • 01.00.02
  • 01.01.00 (Brand Update)
    • 01.01.01

My assumption is that there won’t be a second edition for a very long time. The other assumption is that the location of the most recent guide will always have its content change. It’s probably best practice to always include the new version of the guide in with the archive.

Looking back, the revisions for the guide have been saved. It unfortunately automatically publishes the page when you revert the change but it’s still possible to obtain the versions so I could start the archive for the project management guidelines (like my example above) at any rate. Maybe I could use a plugin to create archive pages. While I didn’t find any plugins specifically for what I’m looking for I am familiar with pods – where I could create custom post types and set up the infrastructure to house and display the information. I don’t want to clutter up the posts or pages in the WP dashboard with archive information.

I’m sold on making a version page and linking to older versions. I’m apprehensive about starting down the pod pathway without knowing exactly what I’m trying to achieve. This feels like a new project.

If this IS a new project then how should I address the versioning for this current project? Like stated earlier, the revision information is saved in WP so I can mine that data and create the versions after-the-fact. I think the only difference between a future when the versioning infrastructure is set up vs. now (aside from having a location for versions) is that the version would be visible on the document itself. Adding the version code to the guides in some way is easy enough to do. Perhaps it exists as a line after the title. Something like…

Project Management Guidelines
v 00.02.02
Summary: What steps you can take to produce your own creative endeavors.

I like that. I think that about covers this session. In the next session I will build the draft of the content. That should be fun. See you there!

Action Items

  • Add new refinement project: CQ Versioning System
  • Consider adding “Style Guides for Brands” as a project or as part of the branding project.
Session 01: Kick-off
Session 03: Drafting the Guide