DocOps: Technical Communication is becoming more agile.

I have written a few manuals for companies in the wafer fab research and development space, e.g. , Silicon Valley companies that actually do something with silicon! These tend to be older industries, with older engineers and conventions. They like their technical manuals delivered in MS Word. I deliver in Word to these folks, but the documentation usually starts getting written in something more modern.

While I love projects that touch real silicon, I have become more interested documentation that crosses my system administration and software roots in the DevOps world.

DITA is still popular

A lot of technical communications departments are using XML. Docbook has largely given way to DITA (Darwin Information Typing Architecture). DITA is custom made for Tech Pubs and Reuse. Topics, Concepts, Tasks, References & Glossentries are strongly typed and validated snippets of technical information which are assembled as manuals, help systems or other documents as needed via a book map or map. The XML transforms into whatever content type or style is needed. The benefit is highly resuable technical writing.

This method has both benefits and costs. The agility of snippet reuse does not alway translate into agility of writing, or of being in sync with developer flow. It also tends to isolate Tech Pubs from overall development. The trend in development is agile teams using tools like GitHub, and integrating technical writers into agile teams.

DocOps will take over in 2017

The latest expression of this trend was demonstrated by Andrew Etter of Palantir, who gave a talk on Modern Technical Writing at the Society for Technical Communications Silicon Valley Chapter last month and also published a book with the same title.

Etter’s approach anticipated my own: Write Snippets in a lightweight markup language like Markdown, use the same git or GitHub repositories as developers, and transform/convert the documentation into whatever formats are needed. This approach creates the same benefits as formal DITA, without the added expenses, isolation or bottlenecks (of course even markdown can be converted to DITA topics).

The agile development in technical documentation is getting called DocOps, to match the blurring of lines between development and IT in Devops. Check out this article on the DocOps trend.

Corporate Writing Doesn’t Have to Sound Like It’s Written by Committee

We’ve seen this phenomenon at work: perfectly lucid writing being turned into unintelligible hash.  Dilbert creator Scott Adams even turned this tendency into the ultimate prank. I knew a pastor who had a plaque on his wall that read “For God so loved the world, that He didn’t send a committee.”

In the Harvard Business Review this month, is a piece that addresses this tendency, and ways to fix it.  The usual suspects are involved: roles that are not clearly defined, and management structures that impose conflict rather than clarity.  There are some gems in this piece, so be sure to give it a look.

Documentation Avoidance for Programmers!

“This past week on the WTD Slack forum, there was a bit of discussion around a recent presentation titled ‘Documentation Avoidance for Programmers.’ In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.”

Some of these are funny enough to end up in a Dilbert strip, like saying, “It’s on the wiki” (even when you know it’s not).

And then there are more practical ideas, such as “getting others, namely technical writers to create the documentation.”  This is a great idea! Not only do most developers hate writing documentation, but they often aren’t very good at it, since their investment in code does not always translate to good documentation.

Programmers and engineers would usually rather be coding and building things instead of explaining them to others. With documentation, it can take a lot of effort and multiple tries before you get the organization and flow of logic just right and because “experts are hampered by the curse of knowledge. They know too much and can’t identify the assumptions, needed knowledge, and other building blocks of basic that users need.”  A good technical writer can develop documentation that is audience specific, including developer documentation.

For a good programmer, writing documentation is a secondary skill at best. More importantly, it is a waste of a good programmer’s time.

The only thing worse than using a developer to write documentation, is using an engineer to write marketing materials.  I’m sad to say that this also happens! With a few exceptions, you end up with lesser marketing materials, and have wasted expensive engineering hours to do it.  It is better for a seasoned writer to get the engineers input, and then deliver a great product so that the engineer has time to do the same.

The latest web ui fad, until you are sick of it, and then what?

It has become apparent that UIs and Web pages benefit/suffer from fashions nearly as much as clothing!  While Steve Jobs and Mark Zuckerberg may have eschewed fashions in favor of zen simplicity, most of the world wants a refresh in what they wear and look at.  Thus as intuitively simple skeuomorphic interfaces gave way to flat and colorful, it didn’t matter that UI guru Jakob Nielsen complained that the flat interface reduced discoverability and led to low information density.  There are other points of contention, and flat interfaces have their selling points in a responsive universe.

But while interfaces change to adapt to new technology, it is also possible that people just want something new to look at.  MacOSX Aqua seemed cool when it first became available, and Apple tried to go after countless attempts to rip it off.  But now it does look dated.

Web UIs seem to suffer more than anything else. It seems like just when a convention yields fast clean easy UIs, a new fad or technology comes in and wipes it out.  One hot fashion that I am completely sick of is “Infinite Scrolling”. I can see the arguments in favor – simplicity, a single action and point of focus, and ease in delivering the single call to action.  But it was only a few years ago that web pundits advised against forcing people to scroll. Even Nielsen has warned that this is not a good idea in several instances.

Here is an article explaining 7 reasons why Infinite Scrolling is probably a bad idea.  Of course it is a bad idea, except when it isn’t! There is no such thing as one size fits all.  Consideration of audience, content and usability should be part of every design.  Usability testing is always a good idea.

Necessary Evils with Moving Parts: Inkjet Printers

One of my tiny niches in the support arena, is local desktop support. A large amount of that is getting a printer to work or getting a machine to work with a printer. Multifunction printers have become a standard piece of equipment, but have some very nice features. You can now print from nearly every device and from anywhere on the internet.

But even without moving parts, these machines tend to be a source of frustrations and problems. It is sometimes worth upgrading to a laser printer, but not in every case. People often ask me what they should buy. Many years ago, I considered HP to be the gold standard, but their quality slipped alongside general company woes. Five years ago, I would have recommended a Canon, and they have done some good engineering, but now you can’t always rely on every model to be a winner from them either.

The evaluation of printer quality is a moving target. Therefore, it is best to do fresh research when looking to do a purchase or a replacement.

Here is a nice list put together by Best Reviews that is a good starting place if you are in the market for a new multifunction inkjet.

…..And despite the scare tactics from printer companies who claim that any other ink cartridge then their own will destroy the printer, I still buy third party ink at places like Cartridge World.

Miscommunicated requirements is top issue for distributed teams

I use Sococo Teamspace as one of my means of online collaboration.  Sococo has recently conducted a survey about the issues that plague distributed teams, especially in a cross-cultural context.  You can read the article here, but one chart stood out in my mind:
miscommunicated_requirements“Miscommunication about requirements” is the top issue, and “Different views on quality” also caught my attention. All of these problems can be dealt with, but those two require a special effort to communicate.

Philip Crosby, and his “zero defects” definition of quality, understands that requirements and quality are inherently linked as follows:

  1. Quality is defined as conformance to customers’ requirements
  2. The system for improving quality is prevention
  3. The performance standard is zero defects—a commitment to conform to requirements
  4. The measurement of quality is the price of quality.

This means one of the biggest issues in development by a distributed cross-cultural team can be dealt with by clarifying requirements. The functional and/or technical specification document can be part of the means of clarification of both requirements and quality.  By making sure that requirements are clear and understood, major issues can be resolved.

It is possible to adapt a functional specification for a variety of cross-cultural situations and also various agile methodologies.

Telling the story of your requirements in a functional specifications is one of the things I can help you with. See my IT/Support/Software page, and contact me for ideas!

How to get started using Opensimulator

If you have been perusing my 3D Web page, you know that Opensimulator is a piece of technology that I have been investing time in and keeping my eye on.  I have links to some rudimentary instructions for getting online/in-world, but there is also a good introduction on the Hypergrid Business blog.

Hypergrid Business is a primary source for seeing what business and education are doing in OpenSim.

Check out this article: What is OpenSim?

Choosing a Content Management System

In 2005 or so, I stopped creating websites from scratch in favor of using a Content Management System (CMS). The benefit was clear: using well vetted code to avoid reinventing the wheel, and being able to focus on design, content and custom functionality. A CMS also allows easy updates to core code as well as design or content changes.  Modules or plugins allow adding new functions easily, and creating new plugins made code reuse easy.

In my first round of research, the Drupal CMS came out on top, and I developed several sites starting from version 4 up to version 7. About that time, I had customers specifically requesting WordPress, so I began creating sites with that as well. About the same time, there was chatter about the fact that Drupal 8 was going to be more enterprise-centric with a difficult upgrade path from 7. While this will obviously fill a need, most of my customers are small businesses that are seeking to avoid complexity and cost.  One response to the difficulties presented by Drupal 8 was to fork the Drupal 7 code into Backdrop, a CMS that preserves the ease of Drupal 7, while implementing some of the newer features found in Drupal 8.

There has long been a perception that WordPress is simple, but not terribly flexible, and is best for blogs, while Drupal and the like is better for full featured sites.  This was certainly true early on, and is still true for large enterprise sites, but with the incredible market share that WordPress has, it has slowly gained a lot of advanced features, at least through plugins, if not the core code itself.

WordPress also has a powerful range of theme options from many existing themes to frameworks for rapid development to minimal themes allowing customization without complete creation from scratch.

As a result of these developments, I have made WordPress my default CMS for my small business customers, for websites or landing pages. WordPress will still have some limitations, so I plan to keep my eye on the Drupal ecosystem, especially on Backdrop for when extra features are needed.  Realistically, my knowledge of LAMP, especially PHP and CSS allows me to be up to speed on any CMS quickly, but my approach to rapid deployment sites makes it desirable to automate installs with scripts and be able to develop custom themes quickly.  I have also done a site for a photographer using Koken.

If you want to drill down into more detail, the CMS Matrix site, allows you to compare features of over 1200 CMSes!

Welcome to my blog

Check back here for helpful hints and other cool ideas related to lead generation, web media and small business IT.