Thursday, November 28, 2013

Wabi-Sabi - This way lies madness!

This post is yet another rant about the quality of the technical writing I have been seeing lately. In a LinkedIn discussion-forum about technical writing, I came across a link to a blog post wherein the author seems to both embrace and exemplify the aesthetic called "wabi-sabi" (a Japanese term that generally means embracing imperfections for their artistic value) for technical writing. Personally, I see that as nothing but an excuse for bad writing. As LinkedIn does not have room in their comment field for a rant of this length, I have posted it here.


Perfection in anything is impossible. However, I believe the Wabi-Sabi aesthetic has no place in technical writing. Wabi-sabi embraces imperfections almost to the point of idolizing them. Wabi-sabi began as a mindset of appreciating the imperfections that come with age and wear but has become an aesthetic of intentionally introducing flaws for artistic effect. While technical writing is "an art" it is not Art (with a capital 'A'). For far too many technical writers - or at least people who like to call themselves technical writers - this wabi-sabi aesthetic seems to have become nothing but an excuse for bad writing. 

This article (and the author's entire blog) is a perfect example. There are so many errors it is almost unreadable. It strikes me as nothing more than "content" generated by the vast internet-content grist mills. I understand that this author is very likely not a native English speaker. However, he has chosen to write in English and to write - of all things - about writing. Therefore, it is reasonable to expect said author to actually learn to use the words, idioms, and grammar of said chosen language. He hasn't even come close.

Thursday, August 1, 2013

A flizba by any other name

Warning: This post is mostly a rant.


I read a lot of technical documentation. Software manuals, mostly. Some programming books. 99% of all these books, posts, and guides are utterly worthless. And half of each document or book in the remaining 1% is fluff that I could do without. Because most of these books "cover" very technical topics, it is hard to describe just how nonsensical most of the writing is, in terms a layperson can understand. So, I decided to write an example based on something everyone is familiar with. What follows is a description of a common household object as it would be described by most software manuals today, with the name changed to confuse the innocent. Grammatical errors are intentional. Let me know if you can figure out what the hell I am talking about.

The Flizba Model Paradigm

  • A flizba is a very important device around the building. A flizba has a handle and can be used to swat flies. A flizba can also be used to remove dirt.
  • A flizba is longer than a typical breadbox but the total volume is less than that of the space inside a breadbox.
  • Flizbas can be made by hand or can be made in factory. Preferably one that does not have a witch flying around in it.
    • Important Note: You should not use a flizba to swat at a witch which may be flying around in a factory.
    • When making a flizba by hand, be sure to wrap the wire very tightly.
  • To get to the flizba, turn the doorknob to the left (unless the door is not a door, in which case use the appropriate method, as desired).

The contents of this post is Copyright © 2013 by Grant Sheridan Robertson.

Wednesday, June 12, 2013

FrameMaker Tables & Anchored Frames

Introduction

For my second post about FrameMaker, I thought I would focus on objects with
what I have termed "text-centric outsides." As I explained in my last post
(about FrameMaker), these are objects whose outsides interact with the object
that contains them in a "text-centric" manner. In other words, you can insert
them at a particular point in a text flow and they move along with the text.
There are only two objects that do this: tables and anchored frames. Now, many
books will talk about inserting other types of objects (what I call "graphic
objects") into text but fail to mention that what really happens is FrameMaker
automatically inserts an appropriately sized anchored frame and then sticks
that graphic object inside the anchored frame. In my opinion, it is better to
understand what is really going on. Once you have a solid understanding of the
fundamentals, it is much easier to build up various combinations of these
objects to achieve the desired effect.

As I mentioned in my last post, I will not be repeating all the basic steps
for inserting tables and anchored frames. I assume you already know those
things from reading the "help file" that comes with FrameMaker or one of the
many books that are available. Instead, I tend to dig a little deeper than most
books bother to explain. I like to experiment around the edges and find the
limits of the software I use. This post is based on that experimentation.

Tuesday, May 7, 2013

Understanding FrameMaker Frames

Most books and manuals about software merely state what each menu item does or which menu items you need use in order to accomplish some specific goal. Interestingly, that goal always seems to be something that can be easily done by pulling down a couple of menus. I almost always find myself wanting more. I want to know why the software behaves as it does. Is there some underlying philosophy or grand design? This post is an attempt to provide a little help in this regard, for people who use Adobe FrameMaker.

Introduction

Due to the rich complexity of how frames and objects can be used within FrameMaker, it is easy to get overwhelmed by all the different combinations. However, after working with FrameMaker, I have discovered a very simple conceptual model for classifying this behavior which, I believe, will make it a lot easier to understand and keep track of how these things work and work together.

I will not pretend to teach you everything you need to know about FrameMaker in one post. Nor will I bore you with yet another detailed repetition of menu items. I will assume you have already read through the user manual and are familiar with the basic operations necessary to create and manipulate frames and other objects on a page. What I attempt to teach in this post is a way of looking at how these things work in the background so that it will be much easier for you to remember what fits within what and why, as well as help you figure out solutions to difficult design problems using a rational plan rather than a lot of trial and error.

Monday, September 24, 2012

As-Built Document Flow

Here is a Microsoft Visio diagram I created to illustrate the convoluted processes by which documents move around within my department and finally end up in what is called an "As-Built Packet." This is a more visually appealing - and more visually accessible - version of a classic 'swimlane' diagram. Each horizontal bar is a 'lane' which represents either a department within the organization or a specific role within a department. Most of the shapes were found in the selection provided with the software. However, some of them I had to create myself, either from scratch or by modifying shapes provided. Specifically, I created the filing cabinets, the blueprint, the clock, the notebook, the brown accordian file, and I added the hard-hat to the contractor. I also created the custom conveyor-belt line type. I strongly believe that visual metaphors such as these make it much easier for people to understand and internalize the message of a diagram as opposed to just a bunch of text in boxes.



(Click on the image to go to a full-size .PDF file of the diagram.)




The content of this post is Copyright © 2012 by Grant Sheridan Robertson.
This diagram is posted with the permission of my boss.

Wednesday, June 27, 2012

Wood Carving & OneNote

Way back in 2003-2004 I fell in love with Microsoft OneNote. The first version, OneNote 2003, was a little tricky to use when using handwriting. There were lots of questions about it in the newsgroups. After many hours of trial and error, spread out over several weeks, I finally figured out how use the handwriting feature in a manner that would produce consistent results. Being the helpful newsgroup maven that I was, I sat down to write up an explanation for all of this. When I was finished, I realized that I had enough for a magazine article. I hunted around for a magazine that would publish my article and found one which would take it for no pay, but at least I would then be a "published author." All they asked is that I add some photographs to illustrate my techniques. So, I sat down and took a bunch of screen shots, took a picture of my hand holding a stylus, and used PhotoShop to put them together to make it look as if I had taken a perfect picture of my hand over the screen. The publisher loved it.

An example illustration from the article.


Unfortunately, the magazine went out of business before they had a chance to publish my article. And soon after, Microsoft came out with an update that completely changed the way the handwriting features worked, so my article was moot. But it is still a really great article, and a wonderful example of my skills as a technical writer, photographer, and illustrator. Rather than post the article here, and letting all my beautiful formatting get all munged up by Blogger's HTML handling, I have posted the article up on Scribd.com here.



The contents of this post is Copyright © 2012 by Grant Sheridan Robertson.

Tuesday, February 7, 2012

dSRCI - Citations

Part 1 - Introduction
Part 2 - .sci Top Level Domain
Part 3 - Citations



In my past two posts I have introduced the distributed Scientific Research Collaboration Infrastructure (dSRCI) and then discussed my proposal for a new, perpetual Top Level Domain (TLD), called .sci, for scientists to use to uniquely identify their contributions on the internet. The second  piece of this puzzle (arguably more important than the .sci TLD) is a consistent data standard so posts, papers, and articles – what I am calling  “Artifacts of Collaboration” (AoCs) – written by scientists can be crawled, indexed, traced, analyzed, and rated, regardless of where they may be created, stored, moved, or distributed. This data standard will consist of the following parts:
  • A consistent, universal citation system
  • A standardized vocabulary for
    • Relationships between people
    • Relationships between artifacts
    • Relationships between the people and the artifacts.
    • Topics discussed.

In the rest of this post, I will discuss citation systems, how they apply to what we are trying to accomplish here, and a simplified citation system which I think will make it much easier for scientists to use regardless of where they may be posting.

Citation Encoding:
Ahh, a consistent, universal, useable citation system. I have been stalking this mythical beast for years now. Everyone I ask inevitably says, “Just use Dublin Core” (DC) as if DC actually was a consistent citation standard. To my mind – and for the purposes of this project – DC is meaningless because it can mean anything. DC is so “flexible” that anyone can use any of its tags and attributes for just about anything they want. I mean, what the heck does “creator” mean anyway. The author? The publisher? The producer of a film? What? For some people, every citation could reasonably have the same three-letter value for this attribute. I have hunted and searched for any explicit definition of how to use DC in a consistent manner that has been widely accepted, but to no avail. It seems everyone who is designing a system to use DC just makes up their own interpretation of what goes where and what it means. So, in the end, DC is about as useful as simply saying
Random garbledy gook that we let every individual program parse in its own way
If someone out there can prove me wrong, then please do so. I would be so ecstatic that I would ride my scooter all the way out to where you are and hug your neck.

With all the Library Scientists out there who know so much about what is necessary for a good citation, I would think someone would have done all this by now. And, with how darned cooperative librarians tend to be, I would have thought that any good system  would have become widely accepted by now as well. However, again, I haven’t found anything. If I have to, I can make up something myself. If people don’t like it they can suggest something different. But I am not in much of a mood for bickering back and forth on esoterics or theories. Some may suggest that I should at least base my new system upon Dublin Core. However, I now believe that DC has gone the way of Unix. There are so many deviations that it has now simply become a deviant.

I am also aware of the Zotero project and how they use special RDF formatted citation information (often using DC) to download citations from websites that provide it. However, I would prefer that the citations for this system not require an entire paragraph of RDF to cite a ten-word sentence. And, I would prefer that they also be relatively human readable when cut and pasted into a text file or other document.

Both of these existing types of citation systems are certainly in wide use but I still feel they fall short of what will be necessary to facilitate the kind of collaboration we desire. DC is too flexible - thus too ethereal - and current RDF standards are too verbose. So, I propose a new citation system be created. A system that does an end run around the problems of inconsistent citation standards and verbosity. In order for this new citation system to be successful, I believe it must meet the following requirements:
  • There must be a unique identification for each contributor and each of their individual contributions,
  • These citations should be embedded within the documents, contributions, and other AoCs (Artifacts of Collaboration),
I have covered the issue of creating a unique, permanent identifier for each scientist. Now I will address the issue of creating a unique identifier for each contribution from each scientist. Remember, all we are looking for is a clean and simple way to differentiate between all the different contributions made by a particular scientist. It seems to me that the simplest, easiest means to do this is to simply apply a date and time stamp with one-second resolution. (If you know of any scientists who can make more than one significant contribution in a single second let me know. I would really like to meet them.) So, the URI for a contribution would be something like “scientistnameYYYY.sci/YYYY-MM-DD_HH-MM-SS” or perhaps “dSRCI.net/scientistnameYYYY.sci/YYYY-MM-DD_HH-MM-SS” Now, the first impulse of many is to try to imagine using either of these URIs as URLs which then leads one to imagine all those thousands of subdirectories, one for each contribution. But remember, a URI is merely an identifier. It does not have to resolve to a URL. In other words, there does not need to be an actual web page for each of these URI. It is just a label. Also remember, I expect there to be copies of these documents/contributions/AoCs spread throughout the internet. The identifier is merely a means for search engines to … well … identify each copy of each contribution, index it, and make it available to researchers.

Sometimes people would like to refer to a specific section within a document. This can be accomplished using this simplified citation system simply by appending an XML “fragment” to the citation URI. A “fragment” is really not much more than an additional string that starts with a pound/hash/number symbol (#). So a citation indicating a specific paragraph of a contribution might look like this: “scientistnameYYYY.sci/YYYY-MM-DD_HH-MM-SS#paraXXX.” I will have to do some research to see if there is already a standard system for designating these types of within-document-locations. I know Adobe uses something similar for indicating the locations of annotations within the text of .PDF files. I will have to see how that works and if it is available to use.

Embedded Citations:
Another problem with current citation systems is that most of them do not embed the citation directly into the item being cited. The citation is applied as an external label. RDF points to a document and says, “That document has this citation.” Of course anyone can create another RDF tag that claims the document has yet a different citation. And if the document is moved or its server goes down, then all those RDF tags become worthless. When the citation is embedded within the artifact itself (whether it be a .PDF document, word processing document, web page, or just a comment on a blog) then that artifact can be moved or copied almost anywhere and it can still be found and indexed by search engines. (Naturally, if the only copy lies behind a paywall then we have a problem.)  Before search engines began digging into the actual document contents, this would not have been a viable solution. But now that Google and Bing index every word in nearly every document posted on the internet, there is no excuse to still rely on labels that are metaphorically merely laid down near to documents rather than being permanently attached. Pictures have EXIF data, PDF files have embedded metadata, and so do most word processing file formats. Currently, there is no means to easily embed the appropriate unique citation within these documents other than manually going to the metadata dialog within the software for each and every individual file. And, sure, people can manually type out one of these citations in their blog or forum posts, but who wants to go to that trouble? That is what computers are for. Later, in my post on software, I will address a means to make this process easier to do without even really thinking about it.

What about all that other citation information?
That is a good question. Do we really need it in the internet age? Regular citation information is primarily designed to make it possible – though not necessarily easy – for people to find that document in a regular library. Have you been in a library lately? Even at the library, everyone uses computers to look things up. But they have to type in the various bits and pieces of the “legacy” citation, sort through all the false hits, try FirstName, LastName, then  LastName, FirstName, then see if there was a middle initial, then hope the index they are using indexed that document, but never be sure if the document was there but they just didn’t use the right search terms. And this is when they already know exactly which document they are looking for. What a relief it would be to just type in “scientistnameYYYY.sci/YYYY-MM-DD_HH-MM-SS” – or better yet, scan a QR code – and go right to the desired document!

I am not claiming that we should do without “legacy”  citations altogether. Merely that they should be supplementary. I also feel strongly that these “legacy” citations should be consistent, easy to read, and embedded within the document just like the abbreviated citations I proposed above. There is still the problem of a consistent standard. I will work on that some other time, perhaps.

I believe this new citation system, as simple as it is, can really go a long way toward creating  the web of interconnected collaboration we are looking for. But it can only do that if it is consistently inserted in every Artifact of Collaboration as it is created. I will discuss how to ensure this happens in my post on the software necessary to make all this happen. First, however, I need to  discuss the terms – or vocabulary – that can be used to describe the relationships between all the collaborators and these “artifacts.” This is what I will cover in my next post.

The contents of this post is Copyright © 2012 by Grant Sheridan Robertson.