Build an user macro with parameters in Confluence

Overview

Continuing off of last month's post entitled "Build an user macro in Confluence", this document will show you how to write an user macro that accepts input from the user. We will be creating an feature that allows for page redirects in Confluence. The macro will accept two inputs from the user: 1- page title to redirect the current page to and 2- delay before current page is redirect (which should include a default of 10 seconds). From there, the macro will display a basic redirect message, derived in part from the user's input, and load the target page after the delay has passed.

For this tutorial, you should have completed either last month's tutorial and/or Guide to User Macro Templates, Velocity, and be comfortable with HTML and JavaScript.

Parameters

This user macro will take two user inputs: page title to redirect the current page to and a delay time. Let's take a look at these parameters and then break them down:

## @param URL:title=URL|type=string|required=true|desc=URL to redirect to.
## @param Time:title=Time|type=int|default=10|desc=Time to redirect (in seconds). Defaults to 10 seconds.


To declare a parameter, we use the ## @param <parameter name> definition. The parameter name can be anything as long as there are no spaces or starts with a number. It's a good habit to get into naming the parameter names by their purpose.

Next, we have the title of the parameter. The parameter is displayed in the macro's properties when entering the value for the parameter. Here, you can use any combination of characters and spaces as you see fit. The title value should be human readable.

To help the Confluence user macro determine what kind of value it is using and to make the user macro more user friendly, we define the type of input we are providing to the user macro. For the URL parameter, we declare the type to be a basic string (which means the value can be anything). For the Time parameter, we set the type to be int (integer (numbers only)).

For the URL parameter, we set a property called required to be true which tells Confluence that this parameter is mandatory. Not setting this parameter will result in an undefined value and thus disable the macro under it is defined.

For the Time parameter, we use the default property to provide the macro with a default value of 10 (seconds). This is a convenience for the user as they won't need to enter a value unless they want to use something other than the default value.

The last property in both of these parameters is the description (desc). This is the text that will be displayed in the user macro window when filling out the various parameters. You should strive to keep it short, simple, and direct to the point.

Macro Browser Information

As mentioned in the previous tutorial, you don't necessarily need to fill out every field in this section of the user macro but you are required to at least fill out the Macro Name and Macro Title. The others are up to you fill out as needed. But for this user macro I included the following values:

• Macro Name: redirect
• Visibility: Visible to all users in the Macro Browser
• Macro Title: redirect
• Description: Redirect current page to a new URL within a user specified time (seconds).
• Categories: Navigation

Definition of User Macro

Since we won't be including any body information in this user macro, we'll set the Macro Body Processing to No macro body.

Template

For the template (code) of the user macro, we'll break it down into two sections: Setting Velocity variables and the rest of the code.

Setting Velocity variables

We set Velocity variable like this:

#set($variable=value)

For our macro's delay, we need to use the following to set up the input variable as milliseconds:

#set($timeOut= $paramTime + "000")

Here, we are setting the variable $timeOut to be the value of the Time parameter which the user supplies in the macro or the macro provides via it's default value.

Basic redirect message

Next, we need to set up the basic message that this page will redirect the current page to the target page.

<div id="redirectBox">This page will be redirected to <a href="$paramURL">$paramURL</a> in $paramTime seconds.</div>


Note the usage of the parameter variables and not the Velocity $timeOut variable so far. The code provides the wiki page with a few elements that displays a basic redirect notice and provides the user with a link in case the redirect function doesn't work automatically or the user wants to forego the delay and visit the target page sooner than later.

Redirect function

The last bit is the JavaScript function to redirect the page after the specified delay:

<script type="text/javascript">
  function Redirect() {
    window.location="$paramURL";
  }


  setTimeout('Redirect()', $timeOut);
</script>


Ideally, this JavaScript function would be included in a library that your Confluence server makes available globally but since it's a small and, hopefully, rarely used macro, it wouldn't hurt the page load time too much if we just include this function on every instance of the macro.

Complete macro code

## @param URL:title=URL|type=string|required=true|desc=URL to redirect to.
## @param Time:title=Time|type=int|default=10|desc=Time to redirect (in seconds). Defaults to 10 seconds.
#set($timeOut= $paramTime + "000")
<div id="redirectBox">This page will be redirected to <a href="$paramURL">$paramURL</a> in $paramTime seconds.</div>

<script type="text/javascript">
function Redirect() {
  window.location="$paramURL";
  }
setTimeout('Redirect()', $timeOut);
</script>




Resources

• [Atlassian's] Guide to User Macro Templates

Build an user macro in Confluence

As a tech writer, I often find myself using a good collection of Confluence macros in my documentation. So of the most commonly used macros are the table of contents, style, Jira issues, align, attachment, children display, html, and live search. There's actually dozens of macros that I utilize on a regular basis but I commonly use these in some in some combination with each other. For example, I use the table of contents macro nested within the align macro so I can avoid the dreaded long list of anchor links at the top of a document and have the table of contents listed in a floating (left) element so the content of the page can flow around it.

Wouldn't it be nice to combine some of these macros into one "uber macro"? In this tutorial, I'll walk you through the process to do just that: create a table of contents nested within a float left element.

User macro anatomy

Writing an user macro isn't for everyone. It requires some basic knowledge of how HTML and Confluence XML macros works. Plus any skills with CSS, JavaScript, jQuery, and Velocity would be to your benefit to create more advanced user macros. If you don't feel comfortable getting started with this tutorial, you can check out Guide to User Macro Templates by Atlassian for a good overview of what user macros templates are and how to write a basic user macro.

The typical anatomy of an user macro in Confluence looks something like this:

• Macro settings
• Macro definition
• In-macro comments
• Declaration of parameter usage (or not)
• Template (macro code)
• Detailed documentation (external to the macro)

Macro settings

Every macro must declare the following items:

• Macro Name
• Macro Title

These parameters of the user macro are required and the Macro Name should be all lowercase and unique. The Macro Title should reflect the Macro Name but you should be write it so it's human readable as this is the name of the macro that will appear in the macro browser.

The following macro settings are optional but highly encouraged to be filled out:

• Visibility
• You must decide if this macro will be available to everyone or to just the system admins
• Description
• This is the description of the macro that your users will see when selecting this macro from the macro browser
• Categories
• The macro browser can be sorted by different categories of macro. Choose yours accordingly. 
• Icon URL
• If an icon is not defined, Confluence will assign it a generic icon. For faster load times, the macro should be internal to your system. Historically, an icon can be hosted somewhere within the server as long as it is reachable by the standard user. Or, it could be hosted on a wiki page as an attachment.
• Documentation URL
• To say the least, this macro should be documented somewhere on the wiki

Macro definition

The Definition of User Macro is the section of the user macro that allows you to define the Macro Body Processing and it's Template.

Macro Body Processing options

The Macro Body Processing allows you to instruct Confluence how the macro should process the body before passing it your macro. The macro body is what gets display on the Confluence page, if the macro has a body that is.

Option for processing includes:

• No macro body
• Use this option if your macro does not utilize a body
• Escaped
• Use this option to render the contents of the body as HTML markup
• Unrendered
• HTML content will be processed before being rendered
• Rendered
• HTML content is rendered but doesn't guarantee that it will be rendered before the page finishes rendering. 

For our macro, we'll set this parameter to No macro body as we won't be utilizing any body elements.

Template

The Template is where you provide you macro with the code that it will utilize to render the desired results. You can use a combination of HTML and Confluence-specific XML elements, and Velocity.

In-macro comments

As an good code is well commented, user macros should utilize comments as well. To add a comment, you must use the #* comment *# format.

While it's not 100% necessary, it is helpful to include the two comments at the top of your macro: one sentence description (if the description is not filled out) and a link to it's documentation (if no link is provided for the Documentation URL). For the macro we will build in this tutorial, our comment should look something like this:

#* floatLeftToC is a left floating table of content *#
#* for more info, see <tiny url> *#

Parameters

Parameters allows the users to pass in options that the macro may use. Discussing the different options and features of macro parameters can be a whole tutorial in itself.

For the macro we are going to build, it won't take any options or parameters. Therefore, the parameter line in our code should look something like this:

## @noparams desc=Creates a left aligned floating table of contents

Code

For this macro, we want to wrap whatever content into a div element so we can float the element and it's content to the left of the page. To accomplish these, we can do the following:

<div style="float: left; margin: 0 10px 10px 0; padding: 5px 10px 5px 0; min-width: 50px; max-width: 250px; border: solid thin black; border-radius: 5px;">
  <ac:structured-macro ac:name="toc"/>
</div>

Ideally, the CSS would not be inline to the element we are using to wrap around the ToC. In my experience, the CSS should be a globally declared rule that Confluence makes available throughout your wiki.
Note: the border attributes in the style attribute is complete superficial. I like to use this when developing and/or debugging user macros that act as a container.

The nested structured-macro handles the table of contents thanks to a native Confluence macro.

Documentation

The documentation should include the following information:

• Purpose
• Usage
• Intent
• Parameters
• Change history
• Creator info
• Name, email, etc.
• Known issues and/or limitations
• Links to related content
• Attachment of the code

The purpose of the macro should be clearly defined with it's intent. One doesn't need to justify it's existence (as one assumes this macro was created out of a request or to fulfill an existing need).

The usage section should plainly define it's intended usage, and the parameters (if any) are used, and provide a few examples of the macro in use.

Depending on your work environment, you can include the change history of this macro (if you're not using Github or similar services). The same is true with the creator info and attachments of the code sections.

Depending on it's usage, you may want to include a section about known issues or limitations. While the macro should be designed to work with everything in the Confluence environment, it may not due to a multitude of reasons. Sometimes, the most innocent macro make work perfectly by itself but when combined with another, it may break the other itself or other macros. One recent example that comes to mind is a macro that wrapped a div element around an existing Confluence macro that changes the appearance of it via CSS. While this macro was written to only affect that one macro wrapped within it, it caused several issues with the non-wrapped macro on the same page.

Gotchas

It should be noted that if you have a typo anywhere in your macro's template, it will either fail to render the macro, display an error message, or at the worse, cause the page where the user macro is utilized to fail to render completely.
As a happy accident, while I was exploring which macro I should create, I failed to include the closing parentheses for some CSS rules. This caused the macro to not render and Confluence didn't inform me of anything wrong with the macro.

Write the Docs Newsletter – October 2017

http://www.writethedocs.org/blog/newsletter-october-2017/
This month's post includes the following topics:

• Putting our URLs to work – for us and our readers
• The true meaning of “API”
• Proofreading and copyediting your own work
• Defining developer relations/evangelism/advocacy

Quick Tips: New User Introduction to Documentation

Goals of introducing new users to your documentation should generally include generating excitement around the product and instruct users how to use the product. An optional step my include taking care of a one-time user account setup but let's not get carried away for our users first introduction to your documentation.

Overviews

While technical documentation may be rather bland at times, the introduction and/or overview pages are your chance to generate some excitement around the product and entice the new user to explore other facets of the documentation. Use of graphics should highlight the product's features and illustrate ease of use. Cross linking should be used but not abused.

Tutorials

Short tutorials and quick start guides are a great way to introduce new users to the product by showing them by how to use the product. Two good examples are Bootstrap's Getting Started and YoYo's introduction to Gamemaker Studio Basics. Each take a different approach to product introduction and both examples leave the user wanting more. Code samples should be well labelled and, if possible, executable. If videos are used, keep the short (under 5 minutes) and concise.

Registration

If your documentation site requires users to register, make sure it's quick and simple. A good percentage of users will be turned off by the notion that they must register before seeing the content they are seeking. One approach is to have a few pages that are open to everyone (like the introduction, overview, quick start, and maybe a handful of tutorials). If the user is still interested in your product after viewing the open pages, then they don't mind as much to register an account.

The three A's

Introducing new users to your documentation is a lot like an on-boarding process in a HR department. When a new employee starts, they are accommodated, assimilated, and accelerated into the company tools, culture, and value of those first two items. With product documentation, its very similar too:

• Accommodate: give the new user the tools they need to use your documentation to their benefit (excellent navigation, search, current guides and tutorials, and well tagged documents)
• Assimilate: help the new user to absorb the culture of the documentation site (e.g. use consistent terminology and navigation)
• Accelerate: encourage the user by delivering the value of the product through easy to learn tutorials and apply documentation of the product (cross-linking tutorials with content found in guides)

Update: Using Node.js for Text Processing

Last month, I gave a lightning talk on "Using Node.js for Text Processing" at the Monthly Front End PDX Meetup and I'd like to share my slides and updated code sample in this month's post.

For the most part, my presentation didn't change that much but what did change is some of the methods I recently started using which made my code more efficient.

Requirements

The required modules section of the script stays the same:

var fs = require('fs');
var cheerio = require('cheerio');
var shell = require('shelljs');
...

Looping through the documents

For a little more efficiency, I didn't declare a variable to hold the list of HTML documents and instead, piped the shell method of ls directly into a map function which allows the script to loop through each item it finds in the /documents directory that matches the HTML file format.:

...
shell.ls('documents/*.html').map(function(file) {
   ...
}

Convert documents to a string

Then, load the document to a string with jQuery-like features (thanks to the cheerio module):

...
$ = cheerio.load(fs.readFileSync(file).toString());
...

Process content

Finally, we do an if/then statement to find what we are looking for, remove it, and save out the file:

...
if ($('div.footer').length > 0) {
  $('div.footer').remove();
  fs.writeFileSync(file,$.html());
}
...

The complete script

Here is the complete revised script:

var fs = require('fs');
var cheerio = require('cheerio');
var shell = require('shelljs');

shell.ls('documents/*.html').map(function(file) {
  $ = cheerio.load(fs.readFileSync(file).toString());
  if ($('div.footer').length > 0) {
    $('div.footer').remove();
    fs.writeFileSync(file,$.html());
  }
}

Slide deck

Here are the slides I presented: https://docs.google.com/presentation/d/1R0GALRoOzNgTz0gcHIzpf0YQVhM6pLhA22ybM1x6YiQ/edit?usp=sharing

Inserting A Date Stamp into HTML Documents

Introduction

In Using Node.js for Text Processing, I showed you how a simple method to use Node.js processing content of HTML files. In this tutorial, I'll show you another technique for adding content to HTML files using Node.js as a command line interface (CLI) by supplying a script with arguments (flags), set up a basic help message, and append a date stamp to an user supplied HTML file. If this is your tune, let's jam!

Requirements

You should be fairly comfortable with JavaScript in general and have some working knowledge of how Node.js works prior to digging into this tutorial.

Required npm packages

In this tutorial, we'll need to ensure the following packages have been install in your project directory: 

• fs (version ~0.0.2)
• cheerio (version ~0.22.0)
• commander (version ~2.9.0)

Note: This tutorial was written with Node.js (version  ~0.12.7).

Building the script

First off, let's create a new file called append_date.js. As with any typical Node.js script, we start off with a few variables requiring our packages:

var fs = require('fs');
var cheerio = require('cheerio');
var program = require('commander');
...


In this snippet, we use fs to read in the target file, cheerio to manipulate the content with jQuery-like features, and commander for the CLI features of our script. Commander is a wonderful library that I recently discovered and works very well with my documentation and web developing needs.

Setting up the CLI

Like any well written CLI, we should start off with defining how it works. In the following snippet, we define the version of the CLI, how to use it (.usage), and any options (.option) available to the user. Commander is kind enough to provide a basic help output if the user types in <command> -h/--help as well as any usage and options you provide. Commander will display the default help message plus any info defined in the snippet below:

...
program
  .version('0.0.3')
  .usage('[required options] -t <path/file.html> -d <date>')
  .option('-t, --target [target]', '*required* target of HTML file (including the path and file name)')
  .option('-d, --date [date]', '*required* date to append to the HTML file')
  .parse(process.argv);
...


Main processing

Next, we check if both the target file and date flags have been supplied. From there, the script will load the target file and convert it to a string. The script will next check to see if a container element (div#content) exist and decide to create or update it. If the div#content element exists, the script will then look to either create or update the span.date element. With the elements in place, the script will now write out the updated HTML file.

...
if (program.target && program.date) {
  console.log('Updating ' + program.target);
  $ = cheerio.load(fs.readFileSync(program.target).toString()); // load file and convert it to a string

  if ($('div#content').length <= 0) { // if div#content doesn't exist, create it
    console.log(program.target + ' does not have div#content element. Adding it and datestamp now.');
    $('body').append('\t<div id="content">\n\t\t\t<span class="date">Last updated: ' + program.date + '</span>\n\t\t</div>\n\t');
  } else { // if div#content exists, look for span.date
    console.log(program.target + ' has div#content element; looking for date stamp')
    if ($('span.date')) { // if the span.date exists, update it
      console.log(program.target + ' has span.date element; updating it now');
      $('span.date').text('Last updated: ' + program.date);
    } else { // span.date doesn't exist; create it
      console.log(program.target + ' dos not have span.date element; adding it now');
      $('div#content').append('\t<span class="date">Last updated: ' + program.date + '</span>\n\t\t'); // add date under the content div
    }
  }

  var updated = $.html(); // collect updated html content
  fs.writeFileSync(program.target,updated); // save out updated HTML file
...



Fail checks

Like any good CLI, it should fail gracefully by informing the user that something was missing or failed in some way. To accomplish that, our script should check if the target and date flags were not filled out as they will be required for the script to carry out it's purpose. In the following code snippet, the first else if statement confirms if the target file wasn't supplied by the user. The second else if statement confirms if the user supplied a date flag. The final else statement is a catch all if something goes skips a beat.

...
} else if (!program.target) {
  console.log('Target for the HTML file was not provided; quitting.');
  process.exit(1);
} else if (!program.date) {
  console.log('No date stamp was provided; quitting');
  process.exit(1);
} else {
  console.log('undefined error; quitting');
  process.exit(1);
}

This completes the script. At this point, we should save the file and call it appendDate.js.

Note: this script doesn't verify the date string you enter into the span.date element. You could add a check for the program.date content to conform to a specific format using Regex (like /(\d[0-9]){2}-(\d[0-9]{1})-(\d[0-9]{1})/g) but that is entirely up to you.

CLI in action

With script completed, lets test it out on a simple HTML file. Copy the following code and save the file name as test.html in the same directory as your node script:

<!DOCTYPE html>
<html>
<head>
  <title>Date Stamp Test</title>
</head>
<body>
</body>
</html>


Let's test our script by executing the following command: node appendDate.js -t test.html -d 2017-03-30 (or whatever date string you wish to use). Examine the test.html. You should see our date stamp appended to the document with our custom date stamp.

Review

In ~40 lines of code, we created a script that takes arguments from the command line for a target file and a date string, loaded the target file, modified the target file with the date string, and wrote out the target file with the update HTML.

I hope this tutorial was useful and thank you for reading it.

Write the Docs 2017

This month's post includes my notes and thoughts from Write the Docs 2017 conference in Portland Oregon.

Overall, I had a very enjoyable and educational experience (just like last year). However, this year, I had the pleasure of volunteering to help set up the conference. I worked with a great team and look forward to volunteering again next year.

Error Messages: Being Humble, Human, and Helpful will make users Happy

Presented by Kate Voss

Make the error messages more human

• Example of a very unhuman message: "Exception has been thrown by the target of an invocation."

Color warning message may be an issue to some users. Use icons in conjunction color.

Emoticons and/or graphics (humorous, cute, brand-related, etc.) puts a different face on the error message but keep in mind in needs to be appropriate for your brand and audience

Items to consider when writing error messages:

• Put the important info first
• Use fewer words
• "Object first, action second"
• Avoid passive verbs

Remember to:

• Acknowledge
• Apologize
• Explain
• Help

---

My take away: If you are tasked with making error messages "human", know your audience and write short but information messages accordingly.

Building Navigation for Your Doc Site: 5 Best Practices

Presented by Tom Johnson

• Apply design principles ("Universal Principles of Design") to tackle your navigation problem:
  • Hierarchies break down complexity
  • Hierarchies give an idea of the "whole" and show potential related topics
  • Avoid deep nesting
  • Navigate from doc set to doc set
  • progressive disclosure
  • Layer information at different levels. For example:
  • doc portal home
  • product home
  • section hom
  • page
  • Allow navigation within content
  • Even in help, users want to stay inline (sidebar navigation vs. inline link); users are more inclined to click links inline to the document rather than the sidebar navigation
  • Use bottom-up navigation
  • If the viewer reads something that he can do, use, or consider (concept), link it to the respective document
  • Too many links may cause issues with the viewer's decision points (for example Wikipedia entries)
  • Make popular topics easy to access
  • Desire line: "traces of use or wear that indicate preferred methods of interaction with an object or environment" - UPoD
  • Reduce information fragmentation
  • Modularity - "A method of managing system complexity that involves dividing large systems into multiple, smaller self-contained systems" - UPoD
  • Building blocks != presentation
  • Hang signposts along the way
  • wayfinding
  • Example: breadcrumb navigation
  • In a linear guide set, add a link (system) to where to go next

---

My take away: when building navigation for your doc site, keep these ideas in mind:

• Use hierarchies to break down complexity
• Build navigation by category
• Include navigation elements within the content (sidebars and inline links)
• Use metadata content linking to make popular topics easier to access
• Reduce information fragmentation
• Make navigation easy and clear to use

Christy Lutz - You Have Already Succeeded: Design Critique Guidelines Make Feedback Easier

Presented by Christy Lutz

"Feedback makes you stronger."

Ask questions (to yourself or your teams) on how to ask, give, and deal with feedback.

Feedback leads to better working relationships.

Feedback works (it makes things better. Every time.)

What do you need to start using Design Critique Feedback:

• Identify stakeholders (including you)
• Create a scope statement

Write down feedback guidelines (ask for what you need)

How do you start?

• Just start
• Listen and repeat
• Anyone who tells you differently is selling something (you don't need to sell your work)

How do you get people involved?

• Throw a feedback party
• Utilizing stickers can be fun and creative resource

Schedule a design review

Gather feedback anywhere and everywhere

How do you give feedback?

• Criticism
  • passes judgement - Critique poses questions
  • finds fault - critique uncovers opportunity
  • is personal - critique is objective
  • is vague - critique is concrete
  • tears down - critique builds up
  • is egocentric - critique is altruistic
  • is adversarial - is cooperative
  • belittles the documenter/documentation - improves documentation
• You are a person

Tell me, how do you feel? Ask questions.

The goal of the project is the goal of your feedback. Your role is the Defender of the Goals

Defend yourself (defend the feedback to yourself)

How do you deal with feedback? A.K.A., how can I be feedback royalty?

• Build up an immunity
• You are not a documentation vending machine. You own it.

How do you measure your results

• Follow up on the things you don't understand
• Does this support the goals of the project?
• For some feedback, the answer is going to be "no"

Feedback is opportunity for discussion

How do you report your results

It's not about winning

Your goal is not about making everyone happy

Teach design critique guidelines to your team

---

My take away: Feedback is necessary to build better documentation and relationships with your [product] teams and is an opportunity for discussion.
Develop a feedback system that includes:

• Identifying stakeholders
• Defining the scope/goal(s)
• Setting guidelines
• Scheduling reviews
• Measuring results

Feedback is often you (the tech writer) just repeating back what you heard in your terms.

Getting people involved can vary from company to company but the common advice is to make it fun for everyone.

Know the difference between criticism and feedback (negative vs positive). Often time, feedback is little bit of a positive and negative experience (so build up an immunity).

Follow up on things you don't understand.

Testing: It's Not Just for Code Anymore

Presented by Lyzi Diamond

Testing your documentation is good (even if it is informal or formal).

Good documentation pays attention to the small things:

• Consistency
• Completeness
• Correctness
• Contributability

Without automated testing, their documentation would fail.

---

My take away: Reviewing and/or testing documentation for consistency, completeness, and correctness should be important to every doc writer. With formal (automated testing) or informal reviews, this can be achieved with ease (once a process has been set up).

Even Naming This Talk Is Hard

Presented by Ruthie BenDor

• All the good names are already taken
• Because the good names terms are already taken overloaded
• Because naming is reduction and we are bad at choosing what to exclude
• Because names evoke, and we are bad at anticipating that
• Blacklist and whitelist vs blocklist and allowlist - internal/social context awareness
• Because naming matters when even (especially when) we think it doesn't matter
• Why do bad names persists?
  • Because we don't realize they are bad
  • Because we recognize the name is bad but can't or won't justify fixing it
  • sentimental
  • humans hate change
  • overestimated cost of change
  • underestimating value of improved name (projection)
• What makes a name good or bad?
  • bad names
  • confuse, frustrate, misguide, obscure, and offend
  • good names
  • contextualize, explain, illuminate, and empower
• How can we name software better?
  • documentarians: let developers know when their names miss the mark
  • developers: writing software is an exercise in naming things

---

My take away: Naming software is often difficult for many reasons including:

• good name are already overloaded
• people are bad at [product] reduction
• names evoke thoughts and images (both good and bad)
• some people think it doesn't matter (but it does!)

Bad name persist because [product owners]:

• don't realize it's bad
• won't justify fixing it for many reason

bad names confuse, frustrate, misguide, obscure, and offend while good names contextualize, explain, illuminate, and empower

How can we name software better? Get everyone (tech writers and developers) together to have a discussion and go through a few writing/naming exercises.

Everyone's a Player (in a Mid-90s MUD)

Presented by Kenzie Woodbridge

There typically four player types: socializer, explorer, achiever, and killer
Document in game design should emphasis interactive over acting by helping facilities produce vague information and produce cryptic hints when players appear to be stuck
Ways to emphasize acting over interacting:

• Provide a manual
• Include auto-map and auto-log facilities

Socializers are natural documenter; they need your support

• Provide templates, assist with publishing, impose a structure and organization
• Advocate for them to others, Work to include them where they are excluded, give them public kudos

Explorers are anti-documentation; extract the info from them

• Documentation: shows off expertise, keeps icky users away (no pestering), is another thing to have knowledge of
• Reduce barriers (provide templates), rewrite the docs for the audience, help enforce expectation to look at docs first

Achievers are inconsistent documenter; turn it into a game for them

• To motivate achievers: post doc writing/review stats, make doc authors visible, advocate for docs as critical success criteria in projects
• Be available on short notice, provide and enforce templates, publicly thank them

Killers are inconsistent documenter and have an element of destructive chaos (power hoarder); get them to document something

• Self-protection strategies: keep discussions public, document everything (ironically), engage Explorers in the struggle
• Treat agreements like agreements, follow up, follow up again

---

My take: As a tech writer, you'll encounter and need to motivate four different personalities for the purpose of getting them motivated to contribute to the documentation base: socializer, explorer, achiever, and killer.

• Socializers are a natural documenter but they'll need your support. To keep them motivated, provide public kudos from time to time.
• Explorers are anti-documentation so you'll have to extract the information from them. To get them involved, show them the value of documentation and provide templates as a starting point.
• Achievers are inconsistent in their documentation efforts but you can turn that behavior around by turning it into a game. To keep the game lively for them, provide stats and reviews periodically, enforce templates (as necessary), and publicly thank them.
• Killers are inconsistent too but also are power hoarders and getting them to contribute will be very difficult. Employ a self-protection strategy by keeping discussions public, document everything, and treat agreements like agreements. Finally, follow up on your follow-ups.

Treating Documentation Like Code: A Practical Account

Presented by Jodie Putrino
How do we get there?

• Choose the right tools
• Automate
• Collaborate
• Define, then, design
• Adapt

"We're all doc writers now." Don't worry about grammar and spelling, I (the tech writer) will correct that.
Questions they had to answer prior to building, publishing, and implemented their documentation:

• Who are our users?
• What are they trying to do?
• How do they use/find our docs?
• What kinds of docs do we want/need to publish?
• Content reuse?
• What should the docs look like?
• How do we handle versions?
• How do we track usage?
• Can we get user feedback?
• When do we publish?
• How do we handle beta releases?

"The process is not the thing. It's always worthing asking, do we own the process or does the process own us?" - Jeff Bezos

---

My take: Treating document like code is good if your organization supports this process. To get there, choose the right tools, automation processes, and design.

Make everyone a doc writer and ensure them that you don't have to worry about the minute details (we the tech writers will fix it).

Ask your team the following questions when it comes time to implement, build, and publish documentation:

• Who are our users and what are they trying to do?
• How do they use/find our docs?
• What kinds of docs do we want/need to publish?
• Content reuse?
• What should the docs appear?
• How do we handle versions and track usage?
• Getting and using user feedback?

"The process is not the thing. It's always worthing asking, do we own the process or does the process own us?" - Jeff Bezos

Interviewing and Hiring Technical Writers: The Siberian Way

Presented by Sam Faktorovich

Necessary skills for a tech writer typically include:

• Some technical skills (CS fundamentals, OS knowledge, ability to read code)
• Capability and willingness to write documentation

Knowing how to write well != knowing how to teach others to write
One approach to grow your tech writer base is to high a non-technical writer and give them a two month crash course in CS (results may vary).
Pre-interview assignment task:
Write a medium size (1-2 pages) document describing a complex technical topic

• Topic defined by them
• ...? (missed the slide)
• Shouldn't mimic their typical day-to-day documents
• Should show candidate's capability to explain complex things

"Teach, don't tell" - Steve Losh
Tests:

• Easy: Explain the difference between HTTP and HTTPS
• Difficult: Explain the difference between UTF-8 and UTF-16

Other approaches to hiring tech writers

• Recruit your own developers?
• Grow the job market itself? This approached worked for them:
  • Teach tech writing class at one of the local universities
  • Public lectures promoting the profession
  • Technical writing bootcamps
  • Corporate consulting on setting up documentation dept/process

---

My take: Hiring a tech writer can be difficult if that field is lacking candidates. Do you teach a developer to write or a (non-tech) writer to learn how to read code? Both have their pros and cons. Teaching either candidate can be a painful training process if your company goes at it themselves but if you build a community around this need, it will could be a well rewarding experience for everyone.
Consider giving your candidates a writing test:

• Easy: Explain the difference between HTTP and HTTPS
• Difficult: Explain the difference between UTF-8 and UTF-16