It seems I’m writing a minor series on the current status (and possible future direction?) of technical writing and documentation efforts. Both in terms of establishing a foundation for my own professional relevancy, as well as in and for itself because I think documentation has the potential to shape the way that people are able to use technology. I started out with Technical Writing Appreciation and this post will address a few sore points regarding the use of wikis as a tool for constructing documentation.

At the broadest level, I think there’s a persistent myth regarding the nature of the wiki and the creation of content in a wiki that persists apart from their potential use in documentation projects. Wiki’s are easy to install and create. It is easy to say “I’m making a wiki, please contribute!” It is incredibly difficult to take a project idea and wiki software and turn that into a useful and vibrant community and resource. Perhaps these challenges arise from the fact that wiki’s require intense stewardship and attention, and this job usually falls to a very dedicated leader or a small core of lead editors. Also, since authorship on wikis is diffuse and not often credited, getting this kind of leadership and therefore successfully starting communities around wiki projects can be very difficult.

All wikis are like this. At the same time, I think the specific needs of technical documentation makes these issues even more prevalent. This isn’t to say that wiki software can’t power documentation teams, but the “wiki process” as we might think of it, is particularly unsuited to documentation.

One thing that I think is a nearly universal truth of technical writing is that the crafting of texts is the smallest portion of the effort of making documentation. Gathering information, background and experience in a particular tool or technology is incredibly time consuming. Narrowing all this information down into something that is useful to someone is a considerable task. The wiki process is really great for the evolutionary process of creating a text, but it’s not particularly conducive to facilitating the kind of process that documentation must go through.

Wikis basically “here’s a simple editing interface without any unnecessary structure: go and edit, we don’t care about the structure or organization, you can take care of that as a personal/social problem.” Fundamentally, documentation requires an opposite approach, once a project is underway and some decisions have been made, organization isn’t the kind of thing that you want to have to manually wrestle, and structure is very necessary. Wikis might be useful content generation and publication tools, but they are probably not suited to supporting the work flow of a documentation project.

What then?

I think the idea of a structured wiki, as presented by twiki has potential but I don’t have a lot of experience with it. My day-job project uses an internally developed tool, and a lot of internal procedures to enforce certain conventions. I suspect there are publication, collaboration, and project management tools that are designed to solve this problem, but I’m not particularly familiar with anything specific. In any case, it’s not a wiki.

Do you have thoughts? Have I missed something? I look forward to hearing from you in comments!

I’m a technical writer. This is a realization that has taken me some time to appreciate and understand fully.

Technical writing is one of those things that creators of technology, a term that I will use liberally, all agree is required, but it’s also something that’s very difficult to do properly. I think this difficulty springs from the following concerns: What constitutes describing a technology or process in too much detail? Not enough? Are all users of a technology able to make use of the same level of documentation sets? If users are too diverse, what is the best way to make sure that their needs are addressed: do we write parallel documentation for all users, or do we try and equalize less advanced users so that the core documentation is useful to everyone?

The answers to these questions vary of course with the needs of the product being documented and the use cases, but I think resolving these concerns presents a considerable challenge to any kind of technical documentation project, and the way that the documentation developers resolve these issues can have a profound effect not only on the documentation itself but the value and usefulness of the documentation itself. As I’ve been thinking about the utility and value of technical writing, a professional hazard, I’ve come up with a brief taxonomy of approaches to technical writing:

• First, there’s the document everything approach. Starting with a full list of features (or even an application’s source) the goal here is to make sure that there’s no corner unturned. We might think of this as the “manual” approach, as the goal is to produce a comprehensive manual. These are great reference materials, particularly when indexed effectively, but the truth is that they’re really difficult for users to engage with, even though they may have all the answers to a users questions (e.g. “RTFM.") I suspect that the people who write this kind of documentation either work closely with developers or are themselves developers.
• Second, there’s what I think of as the systems or solutions document, which gives up comprehensiveness, and perhaps even isolation to a single tool or application, and documents outcomes and processes. They aren’t as detailed, and so might not answer underlying questions, but when completed effectively they provide an ideal entry point into using a new technology. In contrast to the “manual” these documents are either slightly more general interest or like “white papers.” This class of documentation, thus, not simply explains how to accomplish specific goals but illuminates technical possibilities and opportunities that may not be clear from a function-based documentation approach. I strongly suspect that the producers of this kind of documentation are very rarely the people who develop the application itself.
• In contrast to the above, I think documentation written for education and training purposes, may appear to be look either a “manual” or a “white paper,” but have a fundamentally different organization and set of requirements. Documentation that supports training is often (I suspect) developed in concert with the training program itself, and needs to impart a level of deeper understanding of how a system works (like the content of a manual,) but doesn’t need to be comprehensive, and needs mirror the general narrative and goals of the training program.
• Process documentation finally, is most like solution documentation, but rather than capture unrealized technological possibilities or describe potentially hypothetical goals, these kinds of documents capture largely institutional knowledge to more effectively manage succession (both by future iterations of ourselves, and our replacements). These documents have perhaps the most limited audience, but are incredibly valuable both archival (e.g. “How did we used to do $*?") and also for maintaining consistency particularly amongst teams as well as for specific tasks.

I think the fundamental lesson regarding documentation here isn’t that every piece of technology needs lots and lots of documentation, but rather that depending on the goals for a particular technology development program or set of tools, different kinds of documentation may be appropriate, and more useful in some situations.

As a secondary conclusion, or direction for more research: I’d be interested in figuring out if there are particular systems that allow technical writers (and development teams) to collect multiple kinds of information and produce multiple documentation for different organizations. Being able to automatically generate different wholes out of documentation “objects” if we may be so bold.

I must look into this. Onward and Upward!

Although I haven’t used LaTeX much in the past few years, it was one of the primary tools that hastened my shift to using GNU/Linux full time. Why? I’d grown sick of fighting with document preparation and publishing systems (e.g. Microsoft Word/Open Office), and had started using LaTeX on my Mac to produce all of my papers and documents that needed to be output to paper-formats. Why switch? Because after a certain point of having every tool you use be Free software (because it’s better!), it becomes easier and more cost effective to just jump the gun and by commodity hardware and use a system that’s designed to support this kind of software (managing a large selection lots of free software packages on OS X can become cumbersome).

So why LaTeX? What’s the big deal? Why do I care now? Well…

LaTeX is a very usable front-end/set of macros for the TeX typesetting engine. Basically, you write text files in a particular way, and then run LaTeX (or pdflatex) and it generates the best looking PDF in the world of your document. You get full control over things that matter (layout, look and feel) and you don’t have to worry about things that ought to be standard (titles, headlines, citations with BibTeX, page numbering, hyphenation). The best part, however, is that once you figure out how to generate a document correctly once, you never have to figure it out again. Once you realize that most of the things you need to output to paper are in the same format, you can use the same template and be able to generate consistently formated documents automatically. There’s a “compile” step in the document production process, which means changes aren’t often immediately recognizable, but I don’t think this is a major obstacle.

Word processing and document preparation is a critical component of most common computer users. At least, I’d assume so, though I don’t have good numbers on the subject. In any case, I think it might be an interesting project to see how teaching people how to use LaTeX might both improve the quality of their work, and also the way that they’re able to work. It’s advanced, and a bit confusing at first, but I’d suspect that once you got over the initial hump LaTeX presents a more simple and consistent interface: you only get what you tell it to give you and you only see the functionality that you know about. This might make the discovery of new features more difficult, but it doesn’t limit functionality.

I’m not sure that this post is the right space to begin a lesson or series on getting started with LaTeX, but I think as a possible teaser (if there’s interest) that the proper stack for getting started with LaTeX would consist of:

• A TeXlive distribution. You need the basic tool kit including pdflatex, TeX, Metafont, LaTeX, and BibTeX.
• A Text Editor with LaTeX support: emacs, TextMate, etc. Plain text can be difficult and cumbersome to edit unless you have the right tools for the job, which include a real text editor.
• Some sort of macro or snippet expansion system. TeX is great. But it’s also somewhat verbose, and having an easy way to insert text into your editing environment, both for templates but also for general operations (emphasis, notes, etc.) is incredibly useful, and reduces pain greatly.
• A template management system. This probably needn’t be a formal software system, but just something to organize and store the basic templates that you will use.

And the rest is just learning curve and practice. Onward and Upward!

I have a computer, an old laptop, that I mostly use as the foundation of my stereo system. It’s just a basic system with a few servers (a web server and the music player daemon), and it doesn’t have a running window manager. This configuration usually doesn’t bug me: I connect remotely and the computer sits under the couch, but since my recent move I’ve not had a network connection at home and I’ve defaulted to playing music and managing the system from the console.

This works just fine for me. The virtual terminals aren’t noticeably different from the terminal I get over ssh (as you would expect/hope), except now I have to walk across the room. The people who listen to music with me haven’t yet been other terminal geeks, and so I’ve taken on the role of stereo whisperer. Until a friend looked over my shoulder and wanted to change the track. Using the console is sometimes (often) a slippery slope.

I realized immediately that this situation was much more conducive to learning to use the console than the kinds of introductions to using the console that I’ve typically written. The commands we used were very limited: the mpc program that acts as a simple command-line client to the music player daemon (mpd) and grep. We also used the pipe operator.

There are thousands of commands on most Linux/UNIX systems and remembering all of them can be a bit challenging. The console is a limiting environment basically you can do one thing at a time with it, and you don’t have a lot of leeway with common errors. At the same time, there are a great number of programs and commands that a beginner has no way of knowing about or knowing when to use. Legitimately, the console is both too limiting and expansive to be quickly accessible to the uninitiated. Starting with a very limited selection of commands is way to break through this barrier.

The terminal environment is also very “goal-oriented.” Enter a command to generate some sort of output or result and then repeat. At the end your system will have done something that you needed it to, and/or you’ll learn something that you didn’t already know. When you’re just trying to learn, all of the examples seem fake, contrived, and bothersome because many people already have an easy way of accomplishing that task using GUI tools. Learning how the terminal works, thus, needs a real example, not just a potentially realistic example.

The great thing, I think, is that once you have a need to learn command line interaction, it makes a lot of sense even to people who aren’t die-hard geeks: Commands all have a shared structure that is fairly predictable and inconsistencies are apparent. Perhaps most importantly the command line’s interaction model is simple: input a command and get a response. Advanced users may be able to bend the interaction model a bit, but it is undeniably parsimonious.

It seems, in conclusion, that the command-line is easy to learn for the new user for the same reason it is beloved by the advanced. Ongoing questions, include:

If this kind of realization were to catch on, how might it affect interaction design in the long run? Might “simple to design” and “easy to use” move closer together?

Is there a way to build training and documentation to support users who are new to this kind of interaction style?

I agreed to work on an article for a friend about the collaborative technology “stuff” that I’ve been thinking about for a long time. I don’t have an archive that covers this subject, but perhaps I should, because I think I’ve written about the technology that allows people to make things with other people a number of times, though I have yet to pull together these ideas into some sort of coherent post or essay.

This has been my major post-graduation intellectual challenge. I have interests, even some collected research, and no real way to turn these half conceptualized projects into a “real paper.” So I’ve proposed working with a friend to collect and develop a report that’s more concrete and more comprehensive than the kind of work that I’ve been attempting to accomplish on the blog. Blogging is great, don’t get me wrong, but I think it leads to certain kinds of thinking and writing (at least as I do it,) and sometimes other kinds of writing and thinking are required.

Regarding this project, I want to think about how technology like “git” (a distributed version control system) and even tools like wiki’s shape the way that groups of people can collaborate with each other. I think there’s an impulse in saying “look at the possibilities that these tools create! This brave new world is entirely novel, and not only changes the way I am able to complete my work, but how I look at problems, and make it so much easier for me to get things done..” At the same time, the technology can only promote a way of working it doesn’t necessarily enforce a way of working, nor does any particular kind of technology really remove the burdens and challenges of “getting things done.” More often perhaps new kinds of technology, like distributed version control, is responsible for increasing the level of abstracting and allowing us (humans) to attend to higher order concerns.

Then, moving up from the technology, I think looking at how people use technology in this class allows us to learn a great deal about how work is accomplished. We can get an idea of when work is being done, an idea of how quality control efforts are implemented. Not only does this allow us to demystify the process of creation, but having a more clear idea of how things are made could allow us to become better makers.

The todo list, then, is something like:

• Condense the above into something that resembles a thesis/argument.
• Become a little more familiar with the git-dm (“data mining”) tool that the Linux Foundation put together for their “state of Kernel development.”
• Develop some specific questions to address. I think part of my problem above and heretofore has been that I’m saying “there’s something interesting here, if we looked,” rather than. “I think w kind of projects operate in x ways, where y projects will operate in z ways.”
• Literature review. I’ve done some of this, but I’ve felt like I need to do even more basic methodological and basic theory reading. And even though an unread Patterns of Culture is on my bookshelf, I don’t need to read that to begin reading articles.

That’s a start. Feedback is always useful. I’ll keep you posted as I progress.

I’ve been toying around with the Notmuch Email Client which is a nifty piece of software that provides a very minimalist and powerful email system that’s inspired by the organizational model of Gmail.

Mind you, I don’t think I’ve quite gotten it.

Notmuch says, basically, build searches (e.g. “views”) to filter your email so you can process your email in the manner that makes the most sense to you, without needing to worry about organizing and sorting email. It has the structure for “tagging,” which makes it easy to mark status for managing your process (e.g. read/unread, reply-needed), and the ability to save searches. And that’s about it.

Functionally tags and saved searches work the way that mail boxes in terms of the intellectual organization of mailboxes. Similarly the ability to save searches, makes it possible to do a good measure of “preprocessing.” In the same way that Gmail changes the email paradigm by saying “don’t think about organizing your email, just do what you need to do,” not much says “do less with your email, don’t organize it, and trust that the machine will be able to help you find what you need when the time comes.”

I’ve been saying variations of the following for years, but I think on some level it hasn’t stuck for me. Given contemporary technology, it doesn’t make sense to organize any kind of information that could conceivably be found with search tools. Notmuch proves that this works, and although I’ve not been able to transfer my personal email over, I’m comfortable asserting that notmuch is a functional approach to email. To be fair, I don’t feel like my current email processing and filtering scheme is that broken, so I’m a bad example.

The questions that this raises, which I don’t have a particularly good answers for, are as follows:

• Are there good tools for the “don’t organize when you can search crew,” for non-email data? And I’m not just talking about search engines themselves (as there are a couple: xapian, namazu), or ungainly desktop GUIs (which aren’t without utility,) but the proper command-line tools, emacs interfaces, and web based interfaces?
• Are conventional search tools the most expressive way of specifying what we want to find when filtering or looking for data? Are there effective improvements that can be made?
• I think there’s intellectual value created by organizing and cataloging information “manually,” and “punting to search” seems like it removes the opportunity to develop good and productive information architectures (if we may be so bold.) Is there a solution that provides the ease of search without giving up the benefits that librarianism brings to information organization?

At the end of the day (or even the beginning,) I’m just another geek, and despite all of the incredibly (I’d like to think at least) reasoned ways I think about the way I use technology, I occasionally get an old fashioned hankering for something new. We’ve all had them. Perhaps my saving graces are that I do occasionally need new things (computers wear out, cellphones are replaced, needs change), and the fact that I’m both incredibly frugal and task oriented (rational?) about the way I use technology.

But I’m still a geek. And gear is cool. Thoughts, in three parts.

Part One, Phones and the HTC EVO

I’ve been using a Blackberry for 18 months, and I’ve come to two conclusions: blackberries are great and they have the “how ot integrate messaging into a single usable interface.” I was skeptical at first, and it’s very simple, and I’ve never quite gotten my email to function in an ideal way, largely because I think the Blackberry works really well for email. It’s everything else that I might want to do with my phone that I can’t, and I’d probably like to: I have an SSH client and it’s nearly usable. Nearly. I have IM clients, that are nearly functional. Nearly.

When I got the Blackberry, is and was the most important communication I was doing. I worked for a very email-centric company, and I wanted to be able to stay in the email-loop even when I was off doing something else. These days, IRC and XMPP are a far more central feature of my digital existence, and I tend to think that it’s not an Internet connection if I can’t open SSH. I’m also switching on a much longer public-transit focused commute in the next few week, and being able to do research for writing projects will be nice. I’m not sure what the best solution is exactly, though the HTC EVO is a pretty swell phone.

As the kids these days say, “Do want.”

Part two, Infrastructural Computing and Home Servers

I’ve fully adopted an infrastructural approach to technology, at least with regards to my own personal computing. That was a mouthful. Basically, although I work locally on the machine that’s in front of me (writing, email, note taking, collaboration,) much of the “computing” that I interact with isn’t actually connected to the machine I interact with directly. In some ways, I suppose this is what they meant when they said “cloud computing,” but the truth is that my implementation is somewhat more… archaic: I use a lot of SSH, cron, and a little bailing wire to distribute computing tasks far and wide, and the process of moving everything in my digital world from a laptop that I carried around with me everywhere (college,) to a more sane state of affairs has been a long time coming.

Right.

The long story short is that aside from a machine (my old laptop) that’s at capacity powering my “stereo,” I don’t have any computer’s at home aside from my laptop, and I tend to take it everywhere with me, which makes it unideal for some sorts of tasks. Furthermore, without an extra machine setting around, file storage, some kinds of backups, are somewhat more complicated than I’d like. So, I’m thinking about getting some sort of robust server-type machine to stick in a corner in my apartment.

Not exactly sure what the best option is there. I’m burdened by: frugality, sophisticated tastes, and the notion that having quality hardware really does matter.

More thinking required.

Part three, More Laptops

So I might have a laptop related illness. Back in the day, laptops always seemed like a frivolity: underpowered, never as portable as you wanted, awkward to use, and incredibly expensive. Now, laptops are cheap, and even the Atom-based “netbooks,” are functional for nearly every task. I tend to buy used Thinkpad Laptops, and as I think about it, I’ve probably spent as much on the three Thinkpads, all of which are still in service, as I did on any one mac laptop.

The thing about my current laptop is that when you think about it, it’d make a decent home server: the processor has virtualization extensions, the drive is fast (7200 rpm) and it can handle 4 gigs of ram (and maybe more.) What more could I want? And I distributed things correctly, the “server” laptop could be pressed into service as a backup/redundant laptop, in case something unforeseen happened.

Or I could dither about it for another few months, and come to some other, better, fourth solution.

Onward and Upward!

I’ve done a little tweaking to the archives for dialectical futurism recently, including creating a new archive for science fiction and writing and being who I am this has inspired a little of thought regarding the state and use of archives of blogs.

The latest iteration of this blog has avoided the now common practice of having large endless lists of posts organized by publication month or by haphazardly assigned category and tag systems. While these succeed at providing a complete archive of every post written, they don’t add any real value to a blog or website. I’m convinced that one feature of successful blogs moving forward will be archives that are curated and convey additional value beyond the content of the site.

Perhaps blogs as containers for a number of posts will end up being to ephemeral than I’m inclined to think about them, and will therefore not require very much in the way of archives, Perhaps, Google’s index will be sufficient for most people’s uses. Maybe. I remain unconvinced.

Heretofore, I have made archives for tychoish as quasi-boutique pieces: collections of the best posts that address a given topic. This is great from the perspective of thinking about blog posts as a collection of essays, but I’ve started to think that this may be less less useful if we think of blogs as a collection of resources that people might want to have access to beyond it’s initial ephemeral form.

Right now my archives say “see stuff from the past few months, and several choice topics on which I wrote vaguely connected sequences of posts.” The problem with the list of posts from the last few months is that beyond date, there’s not a lot of useful information beyond the title and the date. The problem with the topical archives is that they’re not up to date, their not comprehensive even for recent posts, and there’s little “preview” of a given post beyond it’s title. In the end I think the possibility of visiting a topical archive looking for a specific post and not finding it is pretty large.

In addition to editorial collecting, I think archives, guides, or indexes of a given body of information ought to, provide some sort of comprehensive method for accessing information. There has to be some middle ground.

I think the solution involves a lot of hand mangling of content, templates, and posts. I’m fairly certain that my current publication system is probably not up for the task without a fair amount of mangling and beating. As much as I want to think that this is an problem in search of the right kind of automation, I’m not sure that’s really the case. I’m not opposed to editing things by hand, but it would increase the amount of work in making any given post significantly.

There is, I suspect, no easy solution here.