I am a computer nerd. It’s not something I have in common with most other technical writers I know. Most of the writers I know come more from art than science, whereas I’ve come to approach my work from the opposite perspective. But lately I’ve been thinking it’s a bit of a shame that so few other writers seem to share that perspective. Particularly because I now see technical skills, especially programming, as a sort of secondary writing skill that others could also benefit from developing.

A lot of the documentation I write is aimed at a somewhat technical audience. They’re people setting up or using a web hosting service. Though I’m not writing for programmers per se, it’s not uncommon for me to include a code sample or instructions for using a programming-related thing (like installing a library or building a tool from source). Being able to read, understand, and write code samples myself, without the assistance of an SME, has enabled me to create more comprehensive documentation faster and with fewer hurdles. Like knowing a second (human) language, knowing the language of computers enables me to communicate with a wider audience. And it’s just a lot more fun to go out there and write something without having to ask for a developer to hold my hand.

Being able to program added depth to my work. Not only do I write the docs, but I can also write tools to help me produce better deliverables. For example, I wrote a collection of bash and Python scripts that reduce the process of generating and deploying my docs from a fourteen(!) step process to a one step process. Not only can I control of the words and screenshots in my docs, but I can also take ownership of the process surrounding the docs.

In short, being able to program has made me a better technical writer. It may or may not have any effect on my literal ability to write, but it has greatly expanded my capacity to produce documentation that people can use and learn from.

If you couldn’t already tell, this is definitely a skill I recommend to my fellow writers. Thanks to a bunch of really smart people, learning to program is easier than it has ever been at any point in computer history. As a matter of loyalty, I recommend taking up Python: it’s a popular, relatively easy-to-understand language (as compared to C or Java) and it runs on all major platforms. If you Google search for “learn python”, you’ll get a lot of resources to get you going, but here are some of my favorites:

• The tutorial I started with some years ago, Instant Hacking, continues to be a fun, single-sitting introduction to computer programming with Python.
• Try Python is an interactive, web-based tutorial. All you need to get started is a web browser and the Silverlight plugin.
• Zed Shaw’s Learn Python the Hard Way is an opinionated, but effective Python tutorial thanks to some excellent exercises.
• The Python website has an excellent list of Python resources for non-programmers.

Give programming a try. It won’t cost you anything (except a little bit of time) and I promise you won’t regret it.

One problem I see with a lot of technical writing on the web, particularly from authors without any formal training in writing on technical subjects, is that examples are undervalued. A lot of writing contains formal descriptive text while containing too few examples that demonstrate reality (or none at all).

Naturally, the reverse problem does appear sometimes, where writers overvalue examples at the expense of formal definitions and abstraction. A lot of the time that’s preferable to no examples, but sometimes, as in every single math textbook I used before I got to college, it’s just as befuddling. Such an arrangement obligates the reader to guess at specifications and rules. Thankfully, I run into that problem with far less frequency than I encounter stuff that’s missing much needed examples.

I don’t think there’s much of a case against examples, even if specific examples might be found lacking. Examples are often fun to write, because they’re usually easy to do (with a few notable exceptions, like screenshots). They’re good to write because they deliver a lot of information in a digestible way.

For example, consider HTTP requests and responses. HTTP requests and responses are how web browsers and web servers communicate. They’re well-defined and they’ve been in use for more than a decade. Although most people don’t know anything about them, they’re not hard to understand. But a description without examples is awfully dry. Here’s my attempt:

An HTTP request is a message (for our purposes, some lines of plain text) to ask for some data from a remote HTTP server. An HTTP request contains a request line (the first line), header lines, an empty line, and an optional message body. The request line contains the method type (one of HEAD, GET, POST, PUT, DELETE) to be performed on the desired resource, the URI of the desired resource, and the protocol version. A header line contains a header name, a colon and a space, and the contents of the header.

An HTTP response is a message which reports on the fulfillment of a received response. An HTTP response contains a status line (the first line), header lines, an empty line, and the response body. The status line contains the protocol version, a status code, and an accompanying reason phrase.

In a word, boring. It’s a very brief summary of the canonical formal description of HTTP, RFC 2616, but it’s mostly accurate. With a couple of extra details (e.g., a list of valid status codes and reason phrases) you could write a valid HTTP request or response with the information above. Though I’ve technically given you all you need, it’s likely that your first (and second and third) attempts to create valid request or response wouldn’t look right. There’s a lot of detail to capture in prose, but an example would clear things up nicely.

So, here’s an example HTTP request, specifically to download the Google home page:

GET / HTTP/1.1
User-Agent: HTTPExample
Host: www.google.com
  

A lot of readers would be satisfied with just that, but writers can provide even better examples by annotation. Here’s the same thing, but with some explanatory notes included:

GET / HTTP/1.1          # "GET" the page at the root (/) using HTTP 1.1
User-Agent: HTTPExample # Program making the request header
Host: www.google.com    # Host name header
                        # An obligatory blank line

We can do the same with an HTTP response (with some unneeded clutter removed for simplicity’s sake):

HTTP/1.1 200 OK                             # Status line with protocol version, status code, and phrase
Date: Mon, 25 Apr 2011 22:22:47 GMT         # Date header
Content-Type: text/html; charset=ISO-8859-1 # Content type and encoding header
Server: gws                                 # Server ID header
                                            # An obligatory blank line
<!doctype html>                             # Response body
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Google</title>
<!-- trimmed for brevity, but I could go on -->

After all that, I haven’t added a ton of new information about HTTP requests. Again, with the exception of a few details, there’s not much there that wasn’t in the prose description. But examples and annotations can help readers “GET” it that much easier, so don’t forget to include them in your documentation.

This is the second part of a two part series, Community. The previous part, Asking for Permission is available in the archives.

Despite my misgivings about STC and some of the problematic processes and behaviors which have evolved in that institution, I still want to engage with its members, since they’re part of a broader ecosystem of technical communicators. I’ve long felt that the people in STC are its greatest asset and I’d love the opportunity to get to know those people in a context perhaps less structured than that of STC. And I’d like to get to know the technical communicators who have, for whatever reason, decided to forgo membership in STC.

Luckily, I’ve found that there is a community of technical communicators developing that isn’t tied to a non-profit status or a particular company. And it’s developing using a core tool of my livelihood, the web. By way of Twitter and through new web-based discussion groups like the Association of Technical Communicators (formerly, the Society of Young Technical Communicators), writers are joining together on an informal basis which has not apparent or available in the past.

One thing that excites me about the community forming is that the foundation of the community is the web. While a formal organization that collects dues and holds elections benefits from a certain kind of seriousness about itself, an open community founded on the web ultimately succeeds or fails on the basis of community participation, not on it’s ability to pay the bills.

Moreover, an informal community with low barriers to entry is going to be more diverse and bring a broader range of experiences to discussions. Barriers like membership dues or Robert’s Rules of Order turn away would-be community participants before they’ve had a chance to see the value of participating.

But perhaps the biggest reason for my excitement is that I feel that there’s an invitation to read, learn, and contribute. In the new web-based community, there’s no need to ask for permission: not only is it ready to have me as a member, but the only thing stopping me from contributing is me.

The recent development of a genuinely web-based community of writers reminds me of open source software communities. In many open source software projects the importance of status and authority is deemphasized (though not wholly eliminated) in favor of practical contribution. Subsequently, formal organizations appear to enable the work of the community, rather than to direct it explicitly. In a culture where making stuff happen is important, a formal or semi-formal organization can do a lot of good.

In particular, I look to the Python Software Foundation as a good example of what such an organization can be. One of the PSF board members, Jesse Noller says, “Our job is to provide resources to the entire Python ecosystem.” For example, the PSF sets aside money each month for groups creating open source software with Python to hold programming events.

I hope that the future of the technical communication community is along such lines. I think we can accomplish so much by creating a community where the objective is to enable sharing and learning by technical communicators of all kinds, regardless of their membership status, their location, their ability to pay dues, or even their self-identification as technical communicators.

The past week has been a busy one for the technical communication community. It’s given me an opportunity to reflect on what excites me and what dissatisfies me about the way the community is organizing itself.

First, a recap: there was something of a blowout over at the Society for Technical Communication. Two members of STC saw, used, and tweeted about a new part of the STC website that was erroneously made available. The next day, the STC Board of Directors announced a delay to the release of the website and blamed the two members:

These activities have cost the Society additional expenses and delays, including lost testing time and staff and developer hours analyzing and rectifying the situation.

In the hours that followed, many STC members (past and present) raised their objections on Twitter. I made a sarcastic response suggesting STC secure their testing. Others decried the implication that the two members acted maliciously. The members in question revealed themselves and described their side of the story, some of which ran counter to the board’s claims.

Three days went by without comment from the board. Finally, STC President Hillary Hart posted a blog entry which reaffirmed the initial announcement:

Imagine a similar incident happening in your organization—two customers getting in to a development site and messing around—What would your company do? How would they address this situation? Our primary concern was to address the problem.

The post and subsequent comments from the president only seemed to fan the flames, including more than one call for the president’s resignation. It wasn’t until Hart issued an apology, four days after the initial announcement, that the situation ceased to escalate.

The episode clarified what dissatisfied me about STC and what ultimately led me to allowing my membership to expire last year. STC has developed a culture in which asking for, giving, or withholding permission has become a core function in and of itself, rather than in service of some larger objective.

A major point of tension in the episode stemmed from a difference in perspective over a rather simple thing: a hyperlink. The two STC members the board blamed saw the link to the STC staging site as a natural thing to click on and investigate, while the board regarded that activity as an “intrusion” and “messing around.”

Considered in the context of permission, the whole episode aligns closely with some of the things I found challenging about being an STC member. In the culture of STC, doing most anything—whether it’s putting on an event or trying a new technology—requires the permission or endorsement of others. A large proportion of my time in STC involved the observation or participation in various permission getting and giving processes, like assigning titles and forming committees. Some of STC’s recent major initiatives, such as the certification program, reflect the permission-centric culture that has developed there. Even when I served as president of the Future Technical Communicators at UCF, which worked closely with the Orlando chapter STC, I found myself seeking permission and consensus for things which were ostensibly under my control.

So this recent episode isn’t really surprising. In the permission-based culture of STC, it’s natural for the board to expect that no new activity might take place without some kind of invitation or request beforehand. But this creates tension with people who haven’t embraced or aren’t aware of that cultural norm. It also produces tension where STC meets the internet, where such permission seeking isn’t expected. This “incident” is merely one very public case of the ill effect caused by STC’s culture colliding with another which doesn’t share its values.

Now that I’ve got the glum part out of the way, on Monday I’ll be writing about what’s got me excited about the technical communication community, after spending a year being a bit down on it.

Sarah Maddox at Atlassian recently blogged about her experience with user comments on documentation:

There’s a lot to talk about: setting the permissions that determine who can add comments to the pages, managing those comments, the sort of comments people make, how many comments we receive, and above all, is it a good thing or a bad thing to allow public comments on the documentation?

Definitely check out her analysis, because it’s top notch stuff. She covers a lot of ground and provides a lot of examples. Ultimately, she’s enthusiastic about comments on documentation, but it left me wondering how that aligns with the expectations and perspective of documentation users.

My concern comes down to one statistic: 56%. Out 39 comments which appeared in a week, Sarah described more than half of those comments as “requesting support” or “requesting help on functionality.” Based on that analysis, it looks like the addition of comments to the mix has vague utility to users. Clearly users are seeing some kind of utility, but it looks like only a narrow majority actually see the same utility. Some use the opportunity to share tips or suggest documentation changes, most use comments as just another place to ask for help.

It’s not a problem per se. For Atlassian or any other organization, comments on documentation can be just another funnel for support requests. But I wonder how users regard that comment form. Are they seeing it as a place to literally comment, to wonder in public about their problems? Or are users seeing it as a close-proximity, low-friction way to reach out to Atlassian? In short, would a private feedback form built into the documentation be as successful as public comments?

Putting myself in the place of the user, I think a private feedback mechanism would be an improvement. When I want to bring something to the attention of the author of documentation, I don’t really care to see my name in lights—more so when it’s something negative—I just want to let them know. But sometimes public commentary is the only obvious path to do that and—particularly on blogs—I’ve opted to avoid the attention that might bring.

Lately, I’ve become a big fan of Armin Ronacher’s Flask framework for developing web applications with the Python programming language. One of the reasons I’m a fan is because of its really beautiful documentation. It’s easy on the eyes and easy to use (fit to print, in fact). In contrast to other web frameworks I’ve used, I can’t remember a time when the official documentation or the source code didn’t immediately answer some question I had.

But what’s really astounding about Flask isn’t just the quality of the official docs, but how well that attitude toward documentation has spread to the community. Of some 30 extensions, all have decent-to-excellent documentation. For example, Flask-XML-RPC is practically prototypal documentation for a small, open-source project. It has installation directions, example usage, testing guidelines, and an API reference. These are all areas where some big projects struggle, yet this project manages to get it all right in a single page.

In contrast to Flask’s extension community is Django’s community of reusable apps and tools. Django, like Flask, is a web framework for Python. While Django has prominent documentation that’s comparable to Flask’s, the projects spawned to support Django haven’t quite caught on. For example, South, perhaps the most popular companion project to Django, has a good guide for users, even if it’s not particularly pretty. But while the  South documentation does an excellent job of describing the software and how to use it, the link to the docs is lumped in with nearly a dozen other links on the project’s less than descriptive homepage.

Part of the difference between the Django community’s documentation ethos and Flask’s can be attributed to a difference in scale. Django is immensely more popular; the huge variety of contributors means that a much wider variance of documentation quality is inevitable. But I think the bulk of of the difference can be explained by the steps that Armin Ronacher took to provide an obvious target for related documentation.

Most importantly, Flask’s documentation theme is provided to developers explicitly for use in their Flask-related projects. I suspect that move pushed many extension developers into a fake-it-until-you-make-it position with their documentation. By encouraging third-party documentation to look like the official copy, many of the extensions now have documentation content that is as good as it looks. Along the lines of the argument that school uniforms improve grades, it would appear that better visual design makes for better documentation.

Additionally, the Flask project also sports approved extensions. In effect, they’re just stars of approval on existing extensions. It’s another method used to foster good documentation. Approval requires the project not only to have documentation, but that the documentation use one of the Flask themes, in addition to following several other good practices.

Presently, Flask is the only project I know of to go to such lengths to encourage good documentation from third-party developers, and it appears to be working. Given the results, it looks like a pattern worth repeating.

I have a complicated relationship with praise for the stuff I do. It’s not Facebook official yet, but I think we’re getting there.

I really like getting unsolicited feedback, because I know it’s likely to be honest, and important to the person supplying the feedback. Depending on the context, there’s a slim-to-huge possibility that a solicitation for feedback will result in a brush off or sugar-coated response, because people hate to give bad news. (There’s also a small possibility that the response will be unnecessarily harsh, because some people are jerks, but this is way less common.)

I like unsolicited feedback received in an indirect manner even more. It’s even more likely to be honest, because the person giving feedback isn’t (intentionally) facing the person who made the thing being commented on. There’s no hard feelings for negative commentary and there’s no sense of buttering up for positive remarks.

Because I like unsolicited feedback and I like indirect feedback, I love seeing comments about my documentation on Twitter. About half the time, it’s in an @reply to some party that isn’t me or my employer. So it’s honest, important to somebody, and easily accessible to me. That’s good stuff right there. Seriously, if you’re making something for public consumption, you need to be subscribed to a Twitter search on [your company] and [your work] (for me, that means “docs” and “documentation”).

But for all that I like about getting feedback that way, I get a little uncomfortable seeing positive feedback. For two reasons, I’m stupefied by approval for my work.

The first of these reasons is slightly irrational: I’m living in fear of regression toward the mean. To illustrate, there’s a tale of questionable authenticity about flight school pilots. After a day of flying, some pilots are reprimanded for especially poor performance while others are praised for doing especially well. Because of regression toward the mean, on the subsequent day of flying, the pilots praised typically did worse while the pilots reprimanded typically did better. Whenever I see positive feedback, I think how it’s conceivable that tomorrow’s efforts will be less likely to earn praise than today’s (never mind that I’m more practiced at my work on any given day than the day previous.)

The second of these reasons is perhaps more sane: I don’t have any idea what I’m supposed to do with the knowledge that someone appreciated what I did. It’s like getting applause at an event. Are you supposed to sit there? Stand up? Wave?

While complaints might be ego bruisers, they’re often actionable. I can deal with complaints because I know I can fix an error, clear up a point of confusion, or even start over and try again, if it’s bad enough. But praise? That’s a signal to not change anything. And how am I supposed to do that?

I work remotely but there are a few ways in which I do not work alone. For example, though I’ve never laid eyes on them, I work with a great team of system administrators, developers, and customer support engineers. I write docs for an intelligent and engaged audience of customers that I’ll never see. Though I may be physically separated from my coworkers and audience, my day-to-day work isn’t some kind of art for art’s sake, done in isolation.

In a lot ways that have turned out to be really important, however, I do work alone. Physically, I work by myself. I have a nice home office set up, but I don’t have a guest chair because I don’t need another surface to collect dust. I also work with a team of people that I have never seen and only interact with on IRC, Twitter, and by email. Perhaps just as importantly, I write for an audience I will not meet because, let’s be honest, that would be seriously creepy.

Working alone can be problematic. For starters, it can stunt your social skills; I know the baristas at my neighborhood Starbucks better than most, since many of my social interactions are with them. Working remotely is a recipe for solitude or, given a certain disposition, loneliness. But on the upside, my office is quiet most days. Nobody’s sauntering over to my desk to tell me to go ahead and come in on Saturday.

But the complexities of working remotely aren’t simply limited to the physical characteristics of the workplace. The work itself changes because you lose something you didn’t know existed until you started to work alone. When I wrote for people that I could see, I had modes of feedback that were essentially free: facial expressions, tone of voice, offhand comments. Now, I have to rely entirely on explicit feedback from my coworkers. It’s not inferior to non-mediated interaction, but it requires a different style of communication.

Working remotely also causes you to learn about and work with your colleagues in a different way. It’s a much faster process to understand your coworkers—their style of communication, their sense of humor, and their preferences—when you interact with them in person (particularly those on the periphery of your work). The “getting to know you period” lasts longer when you work remotely.

None of that is to say that working alone is bad. I like it a lot of the time, despite my increasing resentment over these “snow days” my friends keep talking about. But because working from home is so different, some adjustments are called for to make things go smoothly.

To keep my social skills sharp, I sometimes work from Indy Hall, which is the Independents Hall a few blocks from Philly’s famous (phamous?) Independence Hall. Indy Hall is a coworking space where other people who would also be working by themselves work by themselves in the same room. This works better than you might imagine, particularly because it is populated by some nice, interesting people.

Whether working from home or Indy Hall, however, I’ve also adjusted how I work. While working remotely you must learn to be direct. You can’t simply wait for things to happen. You have ask, directly, does this look good? or what can I do better? because inference is hard to get right in a chat room.

But most importantly, I’ve learned to be more aware of the kinds of feedback I do have access to, whether that’s a comment from coworkers, search queries, or Twitter updates. Working by myself doesn’t have to be a problem—it can even be an advantage—but it it does require some special consideration.

When I started college at the University of Central Florida in fall 2004, I enrolled as a computer science major. I soon switched to the English technical writing track, for a number of reasons, including:

• disappointing quality of instruction from the computer science department,
• a (faulty) prediction that a large percentage of software development jobs would go overseas, and
• an (in retrospect, also faulty) assumption that I wouldn’t be particularly good at making software.

I don’t regret the decision, even though I do regret some of my dumber reasons for doing it. I love what I do now. Not only is writing a pleasure to do, but I find that a lot of the time I’m not bad at it. On occasion, I’m actually good at this sort of thing.

However, I still have one lingering apprehension about choosing technical writing over a perhaps even nerdier profession and that is this nagging notion that I don’t actually make anything of intrinsic value. In other words, the things I make, like tutorials, references, and screencasts, don’t have any value in isolation. It’s easy for me to consider that some piece of software or a particular system that I write about is useful in and of itself, but things I write relating to them are, in a sense, ancillary.

I don’t enjoy this line of reasoning. Foremost because it has the quality of an excuse to simply not try very hard. If it’s not important, why bother? But it also distresses me because it diminishes the actual dollars and cents value of what I do. And not in the sense that such a line of reasoning implies I should be paid less (note to bosses: it doesn’t) but in the sense that if what I do lacks value, then getting paid for it is somewhat dishonest or fraudulent.

Under a strictly practical examination, the idea that what I do lacks value doesn’t hold up to scrutiny. Simply put, I solve a problem that’s typically phrased as a question that looks like this: how do you work this thing (starts at 0:32)? And the solutions I provide to that problem have pretty clear value: they reduce the time, energy, and money needed to do stuff. Thus, in one way, the value of my work can be expressed as the difference between the total amount of time, energy, and money required to do a thing without instruction and the time, energy, and money required to do a thing with my carefully crafted assistance.

So I’m left with the question of whether what I do has any standalone value. Recently, though, I’ve come to the conclusion that this question just doesn’t matter. It’s intellectually lazy to think my work is somehow uniquely faced with the problem of being valueless in isolation. The work that my software developer friends do, for example, is valueless in a certain kind of isolation too. Software can’t run by itself. But should I think less of the work of software developers because it relies on the work of electronics engineers?

Instead, I now see the value of my career and all other careers for what they really are: multiplicative. Just as the work of software developers I know multiplies the value of having a computer processor, the writing I do multiplies the value of the systems and tools I write about. And so it turns out that it’s the relationship to other things that gives technical writing—and practically every other kind of work—its value, not the work itself. It’s by virtue of the relationship, not despite it, that my work is valuable.

Markup languages are used to provide an additional layer of data to plain text, like formatting and providing semantic description for information. I might be understating things here, but there are a lot of markup languages. If you include all the variations on XML, you could probably count hundreds, if not thousands, of different markups used for different purposes.

As a technical writer, though, I don’t concern myself with the vast majority of markup languages; I’m primarily concerned with those used to craft documentation. A huge number of technical writers, myself included, spend much of the day looking at and editing documentation in a markup language, which is then processed to produce other, more consumer-friendly formats like web pages or printed documents. Given that limitation, however, we’ve still got a lot choices. Here are the most prominent I’ve run into in the course of my work:

Unfortunately, there’s no one markup language for every application. If you’re working exclusively with the web, for example, HTML is the way to go. If guaranteed cross-platform consistency is a requirement, XML is perhaps the only choice. Others fall on a continuum of features, cross-platform support, and popularity. While some tools, like Pandoc make it possible to move from one markup to another, the choice of a markup language is still a deeply difficult one, since other writers—including your future self—may come to hate your decision. Below I’ve tried to round up common markup languages for documentation and to provide an overview of each, to help guide you to a selection and to avoid some common pitfalls.

HTML

HTML is the One True Format for the web. All web browsers use it to make the web happen. It’s hugely important. Because of its centrality to the web, it’s also the lingua franca of markup languages: for practically every markup language out there, there’s a tool which will convert it to HTML. Unfortunately, HTML is somewhat cumbersome to actually work in. Partly because the syntax itself is a little on the heavy side, but also because there are varying ideas of how it should actually be used. To illustrate both points, consider that there’s more than one way to mark a bit of text for emphasis:

<!-- Both of these are (usually) bold -->
<b>Some text</b>
<strong>Some other text</strong>

<!-- Both of these are (usually) in italics -->
<i>Some text</i>
<em>Some other text</em>

Though this doesn’t stop some people from writing excellent documentation in HTML. HTML’s somewhat compelling for this purpose actually: practically anything you would care to do—code samples, footnotes, embedded media, etc.—can be done in HTML, but you pay for it in increased overhead doing simple things, like basic formatting and hyperlinks. Though it’s an increasingly less common concern for technical writers, producing printed documentation may be difficult with HTML, since it’s wholly unintended for such use.

Markdown

In contrast to HTML, Markdown is probably the most minimalist of markup languages used by writers. Markdown was created by John Gruber and Aaron Swartz. It’s quite nice to look at without even converting to HTML for use in a browser:

*emphasized*
**strong**
_or_ __like this__.

A [hyperlink][1]
[1]: Looks like this.

As much as I like working in Markdown (many posts here are first written in Markdown and then converted for use with WordPress), Markdown suffers from the lack of an active maintainer. Thus there are several Markdown variants and implementations; while this or that system may claim to offer Markdown support, discovering which features are actually supported is oftentimes a matter of experimentation. Otherwise, it’s a flexible markup, with a wide range of tools to produce pretty, consumable output.

reStructuredText

reStructuredText, a portion of Python’s docutils, is similar to Markdown in that many common formatting tasks, like hyperlinks and emphasis, are easier to do than the equivalent HTML. reStructuredText provides a broader feature set—like sophisticated table formatting and shorthand substitutions—while still maintaining a simple syntax. A cursory look at reStructuredText doesn’t reveal its flaws, however. I use it on a daily basis, and I’ve found that it suffers from somewhat unusual design decisions. For example, you cannot nest formatting: a specific hyperlink cannot be made bold and bold text cannot be italicized. Despite such limitations, it’s a very powerful markup language for documentation, particularly when coupled with Sphinx, which provides tables of contents, multiple output formats, and more.

TeX

TeX (and its most popular variant, LaTeX) is a popular tool among academics, for its ability to handle complex mathematical formulae and for high-quality typesetting. Of all the markups listed here, it’s probably the most capable of certain difficult tasks than any other, but at the expense of ease-of-use. While you can get (La)TeX to produce beautiful output just the way you like it, it may take a lot of effort to get there, particularly if you’re starting from scratch. (La)TeX particularly shines as an intermediary format for other tools going to print. Even if you’re not using it as a primary authoring markup, you may find it in your tool chain nonetheless.

Wikitext

Wikitext often refers to the markup used with Mediawiki (of Wikipedia fame), though other wiki software implements similar markup. Wikitext appears in the context of documentation since so much documentation is now composed collaboratively with wiki software. Unfortunately, different wiki software packages frequently use different, incompatible markups, making the reuse of documentation vastly more difficult than using a markup common outside wikis.

XML

XML stands for eXtensible Markup Language, owing to its core feature of providing a highly flexible, but verifiable format. XML strove to be what HTML has become in many ways: a common markup used the world over. Unfortunately, its flexibility has, in practice, created many competing XML-derived toolkits, like DITA and DocBook. These toolkits are rather complex, making the markup aspect of XML somewhat limited; instead, special authoring tools are typically used to create content which is then stored using the markup. Such tools are the primary hurdle to using an XML-based format: they’re often proprietary and add (yet another) new piece of software to learn and write with.