Yesterday, a coworker and I released a video overview we produced for a product that’s in our techincal preview program now. The new product is fairly expansive, so we wanted to produce something that would help users to understand the product a little more quickly. With that goal in mind, it’s not extremely technical or detailed–definitely more on the marketing level, and definitely in the quick-and-dirty camp.
It was nice to switch gears for once. I haven’t done anything that leans creative in a while.
You can see the video here.
Introducing Lucy Cora Sansbury
My daughter, Lucy, was born on Thursday, 3/27, at 3:10 pm. Early the next morning, at her routine pediatric checkup, we learned that she was born with a congenital heart defect called transposition of the great arteries. She underwent open heart surgery yesterday, 3/31.
I’ve written much more about Lucy and the rough road she’s traveled in her few short days at my personal blog, blog.willsansbury.com.
If you pray, please remember Lucy in your prayers.
Visual Structure workshop sound bites
I’ve been meaning to write up Jean-luc Doumont’s excellent Visual Structure workshop that I attended at STC Atlanta’s Currents 2008 conference.
With the birth of my second kid looming, I know I won’t find time, so here’s some sound bites from my notes.
- Fight against sequencing.
- The only cross-cultural issue that matters to doing business: what does “yes” mean for all cultures involved?
- When faced with a design/layout problem, resist the urge to add ink. Adding ink will not solve the problem.
- Too much freedom is bad for you. Design requires structure and rules.
- If people notice/comment on the design, it is doing a disservice to the content.
- “I have found that all the ugly things are made by those who strive to make something beautiful, and that all beautiful things are made by those who strive to make something useful.” –Oscar Wilde
- Tables of contents work best with only two levels at the front of the book, then an additional two levels in another table of contents at the chapter level.
- Do not let your software help you. Intentionally set all options related to design (especially sizing issues).
- Round bullets throw off alignment. Use square or right-pointing triangles instead.
- Seven-plus-or-minus-two is based on outdated research that was not specifically examining groupings in documents. Doumont says 3-5 is better (3 optimal, 5 maximum).
Automatic e-mail link with topic information
This javascript automatically creates a mailto link with information about the topic in the subject line. Include this in your help systems for a quick and dirty response mechanism.
This script works by parsing the innerHTML value from the first H1 tag on the page, so it needs to be placed after the first H1 in the document.
<script>
var s = "you@example.com";
var p = escape(document.getElementsByTagName("H1")[0].innerHTML + ” (” + window.location.href.substring(window.location.href.lastIndexOf(”/”)+1) + “, Last modified on ” + document.lastModified + “) “);
document.write(’<a href=”mailto:’ + s + ‘?subject=’ + p + ‘”>Send feedback on this topic</A>’);
</script>
Author-it: Expand TOC completely when Web help is opened
This one comes in response to a question on the Author-it users’ forum from Kathi Bruce, who asked:
Is there a way to change the default to have the TOC expanded on open? We would like smaller books (with fewer Chapters and topics)to open with the TOC expanded, but to open larger books with the TOC collapsed. We currently publish to XHTML using the DHTML User Guide template with a custom frameset, and are still using AIT 4.5.
It can be done by adding a little extra Javascript to the dhtml_toc.js template file. Here’s how:
Step 1. Add this function to the dhtml_toc.js template.
function expandTOC()
{
// Expand all TOC links if ExpandTOC variable is set to true
var expandall = <authorit:ExpandTOC>;
if (expandall == true)
{
var aSpans=top.TOC.document.getElementsByTagName('span');
for (i=0;i<aSpans.length;i++)
{
exp(aSpans[i].id.substr(1));
}
}
}
Step 2. In dhtml_toc.htm, add a call to the new function in the onload section of the BODY tag.
<body ... onload="expandTOC();" ... >
If you have multiple functions in the onload, separate them with semicolons.
Step 3. Create a List of Values variable named ExpandTOC. This variable will serve as the toggle switch on books that determines whether or not the book’s TOC should expand by default. This variable should have two values, true and false, with false as the default.
Step 4. Assign the ExpandTOC variable to a book and publish!
Author-it: Tracking down duplicated HTML file names
When two topics have identical HTML file names and are included in the same book, Author-it generates a completely blank, zero-byte file by the shared file name.
There is no method within Author-it for tracking down these duplicate file names (the HTML file name field is not searchable).
However, if you’re using SQL server, you can create an Excel spreadsheet that can help track down duplicates when the dreaded blank topic files appear.
These instructions are for Excel 2003. I’m sure it can be done for other versions, but I haven’t done it.
- Open Excel.
- From the menu bar, select Data > Import External Data > New Database Query. The Choose Data Source dialog appears.
- On the databases tab, select sqlserver, and then click OK. The SQL Server Login dialog appears.
- In Server, enter or select the SQL Server that is used by Author-it. This should take the form of <host name>\<database name> or <IP address>\<database name>. For example, 192.168.3.35\authorit.
- Select the appropriate authentication method for your database. If you are uncertain, select Use Trusted Connection first. If that fails and you do not know the database Login ID and password, contact your SQL administrator.
- Click Next. The Choose Columns page of the Query Wizard appears.
- Under Available tables and columns, expand TOPIC_OBJT.
- Select the OBJT_ID, HEADING, H_CONTEXT_ID, and HT_FILENAME columns and add them to your query by clicking the > button. After each column has been added, click Next. The Filter Data page of the Query Wizard appears.
- Click Next. The Sort Order page of the Query Wizard appears.
- Click Next. The Finish page of the Query Wizard appears.
- Select Return Data to Microsoft Office Excel, and then click Finish. The Import Data dialog appears.
- Select where you want to put the imported data, and then click OK. The data is imported and inserted into Excel.
- From the menu bar, select Data > Filter > AutoFilter. A sorter is added to the top of each column in the spreadsheet.
To find all topics using a duplicate file name, click the down arrow in the HT_FILENAME column header and select the name of the file that is publishing as a blank page. The list updates to show ever topic that has that same file name.
Once you create this spreadsheet, you can save it and reuse it every time you encounter a blank topic from duplicated file names. Data should update automatically, but I usually select Data > Refresh Data just to be sure.
This is completely safe. You can import the data into Excel from SQL, but you cannot use this method to modify the data in SQL. It’s one-way, so very useful and safe for reporting.
Author-it: Change date on published HTML files to the Last Modified date from Author-it
This VB script sets the date on each topic to the last modified date from the Author-it database.
- Add this comment to the top of the HTML template that generates your topics:
<!–
Topic
<pagetitle>
<authorit:SYS_MODIFIED>
–> - Add _SetLastModifiedDatesOnFiles.vbs to the list of additional files on your book or media object.
- Then add
wscript _SetLastModifiedDatesOnFiles.vbs
to your AfterPublish.bat.
- I also recommend adding
del _SetLastModifiedDatesOnFiles.vbs
to the AfterPublish.bat at the end to kill the file from the final output.
One word of caution: if an embedded topic’s content is changed, I don’t believe the modified date of the topic that contains the embedded topic is updated, as that topic only includes a reference to the embedded topic. So I think you could easily get new content with an old date. If that could pose problems for you, test well.
Author-it: User group Firefox plugin
Click the link below to add the Author-it users group to the search engines in your Firefox search toolbar.
Install - Version for Yahoo! groups search
Install - Version for searching on Hamish Blunck’s site
Author-it: Generating a list of topics with date of last modification
In response to a post by Ron C. Johnson to the Author-it users’ group, I wrote a Visual Basic script to generate an HTML file that contains a list of all topics and their last modification date.
- Step one: Modify the custom HTML template to pass the information the VB script will need. Add this to the very top of your HTML topic template:
<!-- Topic <pagetitle> <authorit:SYS_MODIFIED> -->
- Step two: Add the VB script as an additional file on the book template object. This ensures that the script is copied into the publish folder each time you publish.
- Step three: Call the VB script from the AfterPublish.bat file. To do this, add this line:
wscript _CreateLastModifiedList.vbs
Once these steps are completed, a file named _ModifiedFiles.htm is created each time you publish. To incorporate this file into your TOC, create a placeholder topic that publishes with the same name; the VB script will overwrite it with the new file.
The output is extremely raw, but it should be easy to incorporate your own styles and formatting.
We don’t use this in our shipping help, but our Quality Assurance team seems to appreciate it very much.
Download: CreateLastModifiedList.vbs (zip file)
Contents of VBScript follow after the jump. Read more
Good Press
I’m not usually one to toot my own horn, but when one of my help projects is directly cited as a positive in a product review, I can’t pass up the opportunity.
In WS_FTP Server Hones in on the Enterprise, Aaron Weiss wrote (emphasis added):
Pros: Intuitive Web administration; Flexible event-based rules; Well-written online help.
Since tech writers everywhere play the role of unsung hero, I’ll take that, proudly.
