WFH

Now that COVID has kept a large number of technical types in a mostly remote working state, it really does feel like five days in an office thing is dead. I think very few manager types want to believe that and I think that there are probably a non-trivial minority of knowledge workers who enjoy spending many hours a day trapped in loud, crowded spaces with the colleagues. Regardless, I think it is dead and any company that tries to reimpose it on their work force will see their talent migrate away.

It is possible that I am just engaging in wishful thinking. I have never been keen on being in any of the office spaces in which I have been employed. Some were better than others - the ones where I had four walls and a door that closed were my favorites. The ones without any walls were my least favorites.

On the other hand, going to a space that is not my dinning room does have some advantages. I do like having some commuting time; ideally between 15 and 30 minutes. I also like knowing where work is and where work is not. Some offices have had amenities that were enjoyable like coffee and good snacks. I appreciate my house more when I return to it after some time away from it. Not being constantly tempted by TV and household chores is also a bonus.

There are work arounds to regain some of the pluses. My pre-work dog walk is pretty similar to a commute. Shutting the laptop is pretty close to leaving the office. Starbucks is a short drive.

One could wonder about what happens to corporate culture, developing work place friendships, or just the normal bonds of seeing the same people all the time. One could also wonder about what happens to the innovation that happens in the quick casual meet ups in the hallway. Personally, I think most of that is not as important as manager types seem to think. I tend to like keeping home and work separate and don't have tight bonds with co-workers. In some cases, seeing them day in and day out makes the relationships worse. Hallway innovation, in my experience, has never been a real thing.

For some jobs, the office cannot go away. Teachers, mechanics, doctors, etc all require an office. For us knowledge worker types, the office is at best a place to keep stuff and at worst an albatross.

I say lets leave them behind when we crawl out of our COVID holes.

2014

2014 felt like a long year. There were a lot of great things, but they were punctuated by long stretchs of drudgery.Life comes with a certian amount of drudgery. It is unreasonable to expect constant excitment from visiting to the grocery store, folding laundry, washing dishes, supervising a child in the shower, brushing your teeth, helping your child brush her teeth, watching the same episode of Dragon Tales for a week, watching Elsa build her ice castle everyday for three weeks, or being a taxi service to play dates, gymastics, swim lessons, birthday parties, and dance lessons.
The taxi service does, more than occasionally, lead to excitement or at least a moment of joy and/or wonder. I get to see Bug having fun, learn new skills, surprise herself, listen to her stories, and teach me new things. Taxi service is the drudgery that makes me appreciate the wonder of being a dad.
The additional drudgery this year comes from my job. It pays well, but there have been few oppertunities for me to really sink my teeth into anything. The pace of development is slow and most of the features in development are simple from a user perspective. It is hard for me to get excited about documenting a point-and-click UI or the same APIs in a different language. The amount of process and over management exascerbate the boredom. I pretty much have to clear everything I do through a manager and one other person. This is in addition to technical and editorial reviews…. I’m not sure if the solution is a different job or a different attitude; the devil you know or the devil you don’t….
There were also parenting challenges. Bug went through a bit of tantrum storm through the spring and summer. Two of her great strenghts are her independance and her determination (some may call it stuborness). They help her in all sorts of ways, until they mix together in a cauldron of frustration and explode. We had some rough rides, but, hopefully, we all learned how to modulate ourselves and use our natures positively. The darkest moments made me glad that I wasn’t in this alone. Being able to tag out for some relief and having a different perspective on hand made weathering the storms much easier. It makes me respect the work my Mom must have done as a single parent even more than I already did. One thing is certain: Parenting is the most challenging thing I have, and will likely ever, do.
Fortunately, life has a lot of wonder to offset the drudgery:

• There were a bunch a great paddles this year.
• Bug and I got to go on a bunch of great bike rides together.
  
• Bug learned to ride a two wheeler.
• We all went on our first real hiking adventure in the White Mountains.
• We did our first real kayaking trip on Boston harbor.
• We had a number of relaxing camping vacations.

When I look back on the year, it loses a lot of its drabness. The moments of joy and wonder bubble up and remind me what is important: smiles, laughter, hugs, learning new things, sharing nature.

2013

2013 felt like a long year that flew past. I guess that is how time goes as you get older. It was a year with some big changes, but no big struggles.
Part of the reason, the year felt long was the constant balancing act between me time and family time. This year I probably weighted things to heavily on the family time side. It is not a complaint. I love family time. H and Bug are my two favorite people and being with them brings me joy. It is just that I also require time alone to kayak, bike, read, or just decompress. Often I feel like I need more alone time than most people and feel guilty about taking it. Then I fear that the guilt will ruin the alone time, so I don't take the alone time. Then I feel a little mad at myself for not taking the alone time and I don't get the regenerative effects. in 2014, I hope to find a better balance.
I had two big changes in 2013: a new job and Bug going to preschool.
The new job has been a generally positive change. I was miserable and bored at Red Hat. It was tough going from being senior and knowing where all the bodies are buried to being a new kid on the block. I had to learn how the new company functions, the politics, and the culture. That on top of doing the job I was hired to do. It is a good change overall. I did learn a few things about myself though. I like flexible work schedules more than I thought I did, I loathe commuting, and I do better working at home than I thought. I know these things because they are the only things I miss about Red Hat.
Bug heading off to preschool was more of a change than I anticipated. She was totally ready to go. I think she was a little bored with day care. For me the change was a reminder that with a child, things are always in flux. It seems like everyday she is a little more independent or has a new skill or is into some new thing. It is great and sad at the same time. She is doing great and that is what is most important.
Our summer was jam packed with travel. We went to Maine, Colorado, New Hampshire, and Florida. Bug is a great traveler and that is a boon for us. She really seems to enjoy camping and kayaking. We got her out a few more times this past summer. The downside of all the traveling is the lack of downtime.
As get older, I am coming to appreciate the value of downtime more and more. Sometimes it is important to have nothing planned and nowhere to go. H jokes that I cannot just sit around for a day and do nothing which is true. I do, however, appreciate the lack of a schedule. I also find that at work, I find it more important to be able to have short days and see my family than be in the thick of things. Relax, be happy.

The Airs

I recently entered the Air realm. In the fall I got a MacBook Air and then for my birthday I got an iPad Air. They are both light, fast, and pretty to look at.
The MacBook Air was, ostensibly, a work purchase. My previous job had spoiled me with a MacBook Pro as my primary computer and my current job insists that writers need an 8 core desktop PC to do their work. I disagreed and took matters into my owns hand. I got the entry level Air with beefed up storage. It is more than powerful enough for basic needs. I haven't tried any hardcore games or video editing, but everything else runs quickly and smoothly. I have played with iMovie and that is as smooth on the Air as it is on my wife's Pro.
The two most impressive things about the Air are the battery life and the speed at which it starts up. The weight is great, but with a name like Air it is expected.
I have run the thing for a full day without charging it and not gone bellow ten percent battery life. These runs didn't involve a lot of video watching or even too much use of iTunes, but the wireless was always on and e-mail, calendar, reminders, and Safari were constantly running.
The start up time is impossibly fast. It is easily less than a minute from shutdown to fully functional. At start up, my Air loads calendar, reminders, and e-mail. From asleep to ready is instantaneous. It wakes up as fast as my iPad or iPhone. That is impressive.
The only drawback to the Air is the limited storage. I am not sure I could use it as a primary computer without running out of space. I have a large iPhoto library and a mid-sized iTunes library. I could currently move everything from iMac to the air, but the air's disk would be over 90% full. I could get away without moving up the music since I have iTunes Match, but I would be uncomfortable.
The iPad Air was actually H's idea. She wanted an iPad, but didn't want to buy a new one. She encouraged me to upgrade so she could inherit my iPad 3. It has been a successful swap. She enjoys the iPad 3 and I got a new lighter and faster iPad. The iPad Air is a lot like my old iPad except that it is much faster. The speed is noticeable between the 3 and the Air. Things on the Air are just smoother. The Air is also much thinner and lighter. The cut in weight has been great. I never got tired holding the 3 for long periods of time, but it was definitely a two hand job. With the Air I can comfortably sit on the couch and read with one hand. It is not a easy to one hand as a mini, but, for me, the extra screen real estate is a good trade off. I'm not so convinced that the extra thinness is a great thing. At first the edges didn't feel great while I was holding it and typing in bed, but I've gotten used to it.
One thing that I have noticed that isn't great about the iPad Air is that the screen occasionally feels plasticy. The two older iPad, and Bug's mini, have more solid feeling screens. It is not that the Air's screen is bad, it just sometimes doesn't feel as lush to the touch.

The OT is Still Terrrible

I'm once again trying to use DITA to make content. I know that a lot of large companies use DITA to manage large content sets, so I figured that the OT would have grown up a little. It has, but it is still terrible. Just doing a few simple things I have run into functionality that should have been implemented and isn't, a number of inexplicable bugs, and a number of other things that are just harder then they need to be.

For example, why is it that using a topicgroup element means that my child links table breaks? That element is not suppose to have any bearing on the content. Or why do I get random topics that don't generate based on how the files are organized on disk? Why doesn't the repsep element actually do anything when it is supposed to?

I hope that with a little more experience and time, I will come to see that most of the problems are user error. That, however, won't make me any more generous towards the OT or DITA in general. It is clearly a system that was made for complex things and was intended to only be used for big shops with lots of money. Why offer a free toolkit that doesn't really work? It is like one of those annoying freemium sales.

Here is a taste of what you could get if you piney up a bunch of cash....

It would be better to just be up front about the fact that this will cost money to be useful.

Markdown Prototyping

I have been working on a large set of documentation for a prototype that will eventually make it into a product. One issue with the publishing system at my company is that it makes doing prototypes, or really anything not within the rigidly and narrowly scoped model, difficult to set up. It takes a lot of work just to get to the point where you can begin writing.
Since time was of the essence and writing is expensive, I decided to do the prototype outside of the publishing system. I also decided to avoid using the rigid DocBook variant we use. Instead, I figured I do the prototype in Markdown using a combination of Daedalus and Ulysses III. It gives me reasonably full featured Markdown support, flexibility to work wherever I want, easy HTML and PDF exporting, and the stack/sheet metaphor fits nicely with topic based writing. The doc set is a stack and each sheet is a topic. The other nice thing about the plan was that it would be easy to take the content bak into XML since despite the complexity of the variant we use, it is mostly formatting markup.
I wasn't sure how well the experiment was going to work when I started, but a few weeks in I think it is great. I was able to rapidly prototype fifteen topics in about ten days. The prototype pages look fairly close to what our actual system generates. I can quickly make changes to the content as needed and republish. The fact that I can work multi-platform is great. I am not chained to my desk. I can demo changes easily. I can even make updates on the fly using my iPhone.
The flexibility does come at a price. Daedalus, the mobile editor, has limited Markdown support. It does not support things like internal linking, images, footnotes, or tables. Ulysses does support all of these things, however it defers to the more limited capabilities of its mobile peer when sharing. It can also be hard to make use of all the Markdown features on an iPhone or iPad unless you are using a Bluetooth keyboard. For example, I still haven't found the backwards single quote used for code on the native keyboard.
These limitations are minor compared to the effort and time saved using the combination. I'm pretty sure that I could not have gotten as far as fast using the normal tool chain. In fact, I'm not sure I could have done it this fast using XML and a more flexible tool chain.
The fact that I am working in text that doesn't have to be structured in a rigid format makes the work flow faster. It provides flexibility for quick changes, yet also allows for topic orientation.
For final production and long term maintenance, unstructured Markdown is not a great solution. There the benefits of the rigidity outweigh the cost. The rigidity enforces uniformity that large groups of variously skilled writers need to create and maintain content at scale.
For small, fast projects or prototyping Markdown, with Ulysses and Daedalus, have proven to be an excellent solution.

Change is Funny

I changed jobs about two months ago. My prior gig was like eating ramen noodles. You survive, but have heartburn, a headache, and lethargy. In trying to identify the issue I kept coming back to the crazy way they did things. The processes were painfully rediculous and there was no will to change them. There was also the crazy need to build all the tools in house.

The funny thing is that my new gig, which is like a breath of fresh air, has all of the same problems. The current processes are, if anything, more crazy. The tools also built entirely in house.

The biggest difference is that I believe in the new company. The entire company is focused on building the best quality product possible. They believe in investing where it is needed. They take the long view on product planning. It feels good to believe.

At my previous company, didn't believe. I felt like a cog in a machine that was finly tuned to poop out good enough product as efficiently as possible. It wasn't a good feeling. When I feel like I could work at 1/2 speed and still be overachieving, I check out.

So I checked out.

I've got a Byline

Despite being a full time writer, it has been a long time since I've had my own byline. The latest issue of Adoptive Families has a story I wrote in it. The story is just a little, personal reflection on first meeting our little love bug.

Reuse Statistics and Self Justifications

A writer I know recently boasted that his team is reusing around 85% of the topics they write and that it totally justifies their move to topic based writing. I was moderately impressed until I found out that the reuse was across a single product. At that point my skepticism became full blown disbelief.
85% reuse is an incredible amount of efficiency across multiple products. Across a single product's library it is absurd, particularly when the writers claim to be following the mantra "do not repeat yourself." At 85% reuse, the writers may only be writing content once, but they are definitely repeating themselves. It doesn't matter what the content looks like from the writers perspective; it is what the readers see that matters.
Of course when someone is bragging about something like this, what really matters to them is reuse. They had some reuse goal in mind or spent a lot of money to implement reuse and needed to prove they could do it. This may make the team look good to the efficiency experts, management types, and the metric mavens, but it is a lousy way to make content.
The other telling thing about this conversation, which happened over a longish e-mail thread, was how the team responded to questions and criticism. The most common criticism was that the content was choppy, disjointed, and repetitive.
The responses were all self-justifying: It is that way by design because it fits into how Google searches land readers into the middle of pages. (I'm not saying that how Google searches land people into your pages is not a valid concern, I am saying that I have never once heard of a documentation team that designed their content around Google search results.) It isn't choppy, it is streamlined. The "flow" content is wasted effort.
There was no reflection. There was no listening. There was no attempt to address the concerns.
As someone whose sole job is to communicate information, I find the unwillingness to think about criticism about how that information is presented unconscionable. There is always room for improvement. Also, acknowledging an issue doesn't mean you have to do anything about it.
You cannot get too attached to your content in this game. It isn't your baby. It isn't a reflection of your soul. It is information that somebody else created. You are merely the conduit through which it is communicated. Learn to be the best conduit you can.

The Importance of Looking Good

One of the things that really bugs me is content that looks bad or amateurish. I don't think that looks can change the essential nature of a piece of content.
Bad content is still bad regardless of how pretty it looks.
Looks do, however, have some bearing on how seriously a piece of content is taken. If a well written or particularly interesting piece is presented in amateurish or simply ugly way, I may just skip it without bothering to find out if it is good. On the other hand, a well laid out piece of crap may get the chance to waste a few minutes of my time.
The care with which something is presented says a lot about how much the presenter values it or about the skill of the presenter. Something that looks thrown together or looks like it was pooped out by a some kid with a free Web publishing kit, why should I take it seriously? The person creating it didn't.
This is much worse when it is done by professional companies where their is their knowledge and experience. If the documentation is laid out to look like something out of the 90s or has the worst qualities of print with none of the Web goodness, what does that say about the quality of the content?
If the content lacks even the basics for ease of access, why should I trust that I will be rewarded for my struggles to find anything of use?

Map Existing Structures Instead of Using the Three Topic Types

It is not that I don't like the kernel that germinated topics. I do like the idea of breaking big ideas into smaller, more manageable, and reusable chunks. It is one of the cornerstones of good writing.
What I don't like is the reduction of all things into three containers that are both too restrictive and not specific enough. Tasks, for example, cannot contain any conceptual information despite the fact that for most complex actions a reader will need some conceptual information to ground the task and explain its purpose in the larger scheme. Also, given the context free nature of topics, a task cannot depend on any other tasks despite the fact that many tasks are meta-tasks where each step in the task is itself another task.
One way to solve the need for adding context to a task is to redefine task to include an overview block that allows for conceptual information. Another way is to define a concept type that, by definition, precedes a task to provide the required context. Both cases create a more specific, and more useful, architecture for writing.
Similarly, to solve the meta-task issue one could define a new task type that allows dependencies on other tasks. This type, called a procedure, doesn't need to have hard dependencies; it could allow for output generation without inclusion of the sub-tasks. However, it would make it harder to ignore the need for the sub-tasks.
It is not that information architects are not free to make new content types; it is that most don't. They have their three types and try to force everything into them. They ignore the fact that an existing information set will have organically developed topic types that make sense for it. In most instances the argument is that the starting point set was narrative and therefore flawed. It needs to be tamed into the three canonical types for its own good.
The mistake here is that by assuming the new model is better, they lose the native intelligence in the existing structure. They assume it has none and impose it. Unfortunately, this approach typically results in more work and no net increase in the value of the information.
A far better approach is to analyze the structures used through out the existing set and attempt to build types, based on the canonical types, into which the old structure map. This requires some upfront work, but makes the move into topics, or modules, smoother. It also retains the knowledge encoded into the existing architecture. It has grown up as a reflection of the needs of the information, the needs of the consumers, and the needs of the authors. Hopefully, the standardization of the existing structures will result in a net increase in value because it will smooth out the bumps in the existing set instead of chopping it up. It will also give the authors more investment in the task of migration and more able to spot places where it can be improved.
The other benefit of remembering that the structure of existing sets has value, is that it sparks an iterative process. The architecture can be modified as needed. New types can be introduced; old types can be refined or removed.

Just a Bunch of Books

One of the things that have been occupying my brain lately is the differences between thinking of a product library as a bunch of books versus thinking of it as a bunch of knowledge modules. In both models a library will have something called books that are used to organize the content because book is such a well understood concept for organizing written text. Readers expect to see a list of books that will contain smaller divisions called chapters. They understand how to navigate inside that abstraction.
The differences between a bunch of books and a bunch of knowledge modules is mostly a production concern. It will have an impact on the reader's experience since the resulting library can be very different, but it is not something a reader will need to have knowledge of to work with the published content. While I am an advocate of the module centric approach because I think it provides more flexibility for the production side and the potential for a richer experience for the reader, I do not believe that a library constructed using a book centric approach cannot have the same richness as a module centric one.
The major difference between the two approaches is how content is chunked into buckets. In a book centric model, the book is the primary chunk-level. Every smaller block used to flesh out a book is done so with a view to building a single entity. This may or may not lead to what is currently derided as the narrative style of writing where there is a flow from one small block to the next and each block is contextually dependent on the other small blocks in the book. It does mean that the possible small blocks are predetermined by the predetermined set of books. So library design goes something like:

Translation or Internationalization

A while back someone passed around a quote from the FireFox team that said something like "We should strive to ensure that every user, no matter what language they speak, can have a consistent experience with our product." The reason for sending it around was to prod the writing team to strive for the same thing.
I generally agree with the sentiment of the statement. Language shouldn't be a barrier to accessing knowledge or a software product. Documentation and user interfaces should be usable regardless of a person's native language. I won't attempt to argue what subset of languages are useful because that is purely a business/resourcing issue.
The statement got me thinking about the differences between making a UI available in multiple languages and making documentation available in multiple languages. I often hear translation used to describe both efforts, but I think that papers over a lot differences.
UI are not so much translated as they are internationalized. In general, making a UI available in a second language involves translating all of the labels and warning messages into a second, or third, language. So there is some translation being done, but it is fairly simple stuff. Most of the labels and warning messages are single words or short direct statements. It takes skill to be sure, but it is a pretty straight forward task.
Documentation really does need to be translated. In general, documentation requires more than a simple parsing of labels and direct statements into a second language. Yes, there are plenty of instances where documentation is little more than steps and reference tables which are just labels and short direct statements, but that is pretty low hanging fruit. I would also argue that simply because steps are short and direct that because they are part of a larger whole, they really should be treated as more than strings that can be changed without consideration of the context. With documentation, because it is a dense collection of language, you really need to consider the whole body of the work and translate it into a new language. This may mean rewriting parts of the content to be more understandable to speakers of the second language. For example, cultural references always sneak into content because they can help explain complex ideas. There are also structures like glossaries that don't always have direct mapping into the second language.
I have seen strategies for translation that attempt to stream line the process by treating the text like a collection of strings. It seems to the that while it may grease the wheels a little, it cannot produce truly good quality content. The systems all place a number of restrictions on the content originator to make sure the strings can be easily translated. Often it seems you end up with something that is mediocre in multiple languages, but is done quickly efficiently.
Wouldn't it be better to create great content in one language and then, if required, have full translations done. It may not be as efficient, but it will probably make for happier readers.