Thursday, November 28, 2013
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
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
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
IntroductionDue 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
|(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
|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
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.
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
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.
Random garbledy gook that we let every individual program parse in its own way
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),
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.
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.