Since I launched this site last year, I have been looking for an effective way to reuse content on server-installed WordPress blogs. I wanted a solution that’s similar to creating snippets in MadCap Flare.

Flare snippets are the big brother of variables. They’re reusable blocks of content that can store formatting along with the text. They can also include variables and condition tags. You maintain them as individual files and can point to them from multiple topics and projects. A snippet is similar to a text inset in FrameMaker and a linked file in Microsoft Word.

So what’s the equivalent of snippets on wikis and blogs?

The MediaWiki Equivalent: Transclusion

Last year while working on the National Cancer Institute’s BiomedGT Wiki, I used the MediaWiki equivalent of snippets. For example, I wrote a statement that reminded experts that they needed to register with the site and get a login to be able to perform certain tasks. That statement needed to appear in multiple places, so if reviewers wanted to change the language, I needed to be able to update it in one place and have it update everywhere that it appeared.

I used a process called transclusion. To give you the simplest example, I created a wiki template that included the heading Before You Begin and the paragraph that described the registration requirement. I then pointed to that template from other pages using a simple tag with the template name: {{RegistrationRequirement}}. For more information about how this works on a MediaWiki, see the Wikipedia Help for using templates. The Wikipedia templates work exactly the same way.

The WordPress Equivalent: Shortcodes

I first realized that I wanted to deploy a similar reuse feature on my WordPress blog when I created my Free Stuff page. The CSS Book list that appears there originated in a blog post on defining Flare styles. If I want to add to the list, I want to be able to update it in one place and have the current list show in both places.

I had read about various WordPress features for possible reuse, but none of them seemed to be exactly what I wanted. So I posted a question on the Thesis forum, where I can get help on customizing my blog’s Thesis theme. One of the moderators recommended shortcodes.

Shortcodes enable you to reuse content using PHP functions and function calls. If that scares you, relax. My PHP skills are still developing. Granted, I have had a lot of scripting experience, so I do understand functions and function calls. If you don’t understand what functions do, read the Wikipedia article about functions.

In a WordPress blog, you normally include shortcode functions in your functions.php file. Make sure that you create a backup copy of the file before you change it. Fortunately, the vendor who designed my WordPress template (DIY Themes), included a custom_functions.php file. Using this file ensures that when I upgrade the template, I won’t lose my custom functions. Nevertheless, I still keep a backup copy of that file, too.

Here’s the example that I used to generate my CSS Book list. The explanatory comments are preceded by two forward slashes (//).

So, when I want to modify the CSS Books list, I modify the HTML markup in the show_css_book_list function. In every location where I have inserted the [cssbooklist] shortcode on my site, the updated book list appears.

If you want to learn more about WordPress short codes and how you can extend them, see Mastering WordPress Shortcodes. I thank WordPress guru Tom Johnson for sending me the link.

Back to top

Having recently seen and enjoyed the 2009 Star Trek movie, I can’t resist a Borg-inspired title. I’m no diehard trekkie, but I have seen several of the movies. I also watched the original series as a kid and have infrequently tuned in to some of the other series over the years.

Does that make me a part-time trekkie? The level of trekkiness seems to have a scale based on participation and devotion. My partner has followed all of the series, knows all of the characters, and can explain story lines in technical and historical terms. Yet, he would never dress as a Romulan and go to a trekkie conference.

Social media seems to have a similar scale. Some love it. Some hate it. Some try it and “don’t get it.” Others approach it with hesitation and later become addicted.

I have friends who say that they would never use Facebook, and later I receive their invitations to connect. Many have stopped sending me email and only contact me in the Facebook space. Others who didn’t “get” Twitter are now tweeting so much that they’re sprouting wings.

So where does your level of participation fall on the social media scale? Have you joined the throng? Are you ready to become a publisher?

Becoming a Citizen of Content Nation

In Content Nation: Surviving and Thriving as Social Media Changes Our Work, Our Lives, and Our Future, author John Blossom examines how the spreading wildfire of social media has transformed us into a “nation of publishers.” He traces this phenomenon back to its primitive origins, from nomadic tribes to “trade-oriented ownership economies” (p. xvi). Those economies created the need for published materials that began with monuments, scrolls, and primitive books. Subsequent publishing events shaped history and transformed society. Blossom cites Thomas Paine’s Common Sense and the arrival of the Gutenberg printing press as significant turning points.

The recurrent theme of Content Nation (used as the book title and as a description for the entity that we have become) is that the growth of social media publishing is the unparalleled phenomenon—the one that’s changing all the rules. This is most evident in the nomadic nature of free-form publishing. We’re running off in our own directions, tailoring our content to our own needs. Publishing institutions are trying to figure out how to domesticate us.

Most notably, we’re spreading influence in a way that is transforming the world. Our ability to publish on-demand content challenges news sources, exposes product weaknesses, and even saves lives.

Following Your Tribe

How we use social media can depend on which of the three publishing “tribes” we belong to (p. 60).

Personal publishers use social media to gain both personal and professional benefits. If your passion is cooking, you can blog about food and publish recipes. You can start a wiki to collaborate on recipes with other cooking enthusiasts.

Media publishers use social media to “market content and online services.” These publishers have traditionally been “manufacturers and distributors of content from centralized plants” (p. 44). Aggregation of content has traditionally been achieved through a layered pyramid structure. But that model has changed. We’re no longer bound to the layers used to filter and package published content. We can package and mix our own content, aggregating it from our own preferred sources. As consumers of information, this is great for us but challenging for traditional media publishers. Blossom cites The New York Times and The Houston Chronicle as examples of newspapers that have risen to the challenge and adapted well.

Enterprise publishers use social media to improve communication and promote collaboration. But because many businesses still perceive social media applications as frivolous, their adoption rate has been relatively slow. Those businesses are not ready to flatten the corporate hierarchy by giving everyone a voice. Businesses who want to attract and retain younger workers need to change this perception. Blossom includes several examples of forward-looking enterprises that are developing a social media strategy and integrating tools such as blogs, wikis, and messaging.

Understanding the New Rules of Buying and Selling

Becoming a citizen of Content Nation brings both benefits and challenges. It creates new opportunities while requiring that we adapt to new ways of thinking and working.

One of the most significant paradigm shifts is the relationship between buyers and sellers. Buyers have access to a growing number of sites that compare products and prices, enabling them to better discover and understand supply and demand. Blossom points out that this “builds efficient economies that benefit the most people” (p. 97). He cites eBay and Craig’s List as examples.

Feedback from other buyers is more prevalent than ever. When you shop online, do you read the marketing fluff, or do you go straight to the consumer comments? Blossom refers to research showing that a clear majority of consumers seek peer advice and are influenced by consumer reviews and ratings. Last year I was minutes away from ordering two office chairs when I paused to read the customer comments more closely. As a result, I ordered different chairs from a different manufacturer and saved several hundred dollars.

Advertising is still prevalent on the web and elsewhere. Viral marketing still exists. But social media brings on a new method of marketing that Blossom calls the Big Sombrero model. In this model, mass markets give way to more effective small markets, which are based on more direct transactions. An example is the print-on-demand capability of Lulu.com.

With the prevalence of peer-to-peer advice and more power behind small markets, marketers need to rethink their approach. When joining an online conversation, they need to function as peers to gain the trust of the community.

Embracing Change…

In politics

Milestones in the evolution of publishing often centered around politics. Newspapers, journals, books, and television all made us more politically aware. Early blogs piggybacked on existing outlets before becoming news sources in their own right. In Content Nation Redefines How Citizens Influence Governments, Blossom impartially covers ways in which social media now plays a major role in politics. Although blogs were influential in the 2004 election, their influence was ubiquitous in 2008. Regardless of how the political tide turns, we can expect that influence to continue.

In Daily Life

The chapter Content Nation Redefines How People Live Their Lives explores the “social” in social media. We create “spaces for common experiences” (p. 201). We organize events. We build communities that promote cultural identity. We reveal our natural tendency toward altruism. As an example, Blossom cites the role of social media in mobilizing disaster relief after the 2004 tsunami in south Asia.

In Education

For learners, the concept of “just-in-time training” is more crucial than ever. Quoting the author:

…by the time young adults enter adulthood to put their education to use, the world has already changed significantly… Now, as our problem-solving needs shift from moment to moment, our need for education cannot wait for a book to put everything that we need together.

Learning professionals refer to the marriage of social media and education as Learning 2.0. I am very interested in this trend and welcome reader comments.

Looking Toward the Future

Content Nation is one of the more richly detailed and analytical books that I have read on social media. Each topic mentioned here is accompanied by a relevant set of social media rules and examples.

I periodically put the book down to ponder the rules, explore the examples, and oh, yes—get some work done. I took a break before reading the last three chapters, and nothing prepared me for their depth. In a way, everything else in the book was simply preparing for the story told in those chapters.

Blossom looks to the past to predict how publishing will play a part in our future. He returns to the subject of altruism—not as an innate abandonment of self-interest, but as a genetic predisposition to preserve our bloodline. This base genetic altruism eventually gave way to a clan-based version based on trade, setting the stage for the evolution of publishing.

To establish a system of trust, we needed contracts, which became a part of our first published content. As publishing became more sophisticated, it also became more centralized, setting the model for the institutions that we know today—the ones that are challenged by social media. With our “giving to get” nature, we are returning to our altruistic roots, this time with more interest in taking care of the earth and spreading global wealth through such online vehicles as microloans. Blossom brings our story full circle, linking our future to our nomadic, herd-chasing origins.

The book closes with glimpses of the future—50, 100, 1,000, and 10,000 years from now. In Blossom’s visions, what we now refer to as social media is fully integrated into our lives, our work, and in some cases, our chemistry.

I’ll stop there. Now read the book!

Informing by Example

The Content Nation book is a product of social media publishing. The content was first developed and published through a collaborative wiki on Blossom’s Content Nation site. The “post-print” version continues online, demonstrating that “evolving social media forms use mass media more as a transient form than as a final goal” (p. 55).

The Content Nation site features links to many of the sites that are used as examples in the book. I encourage you to explore the site and the links.

Getting ready for the next wave

How will social media affect you? Why should you care?

You should care because it will affect your life in some way, even if it’s an indirect way. It’s not a matter of how, but when.

Just when you least expect it, you will be assimilated.

Back to top

In my last post, I expressed my admiration for wikis as a collaborative solution for project and process management. I didn’t discuss wikis as a publishing platform for technical documentation, simply because my clients haven’t yet taken that step.

Fellow blogger Jason Coleman expressed his views on wiki-based tech docs in a comment following my post. In my response, I promised to report back after participating in the Firefox book sprint at DocTrain West 2009.

Having seen a demo of the FLOSS Manuals site last fall, I had been looking forward to the Firefox book sprint with eagerness and curiosity. I had never participated in a real-time, collaborative writing event of that magnitude. So on March 16 and 17, I joined several writers in a conference room in Rancho Mirage, with other writers participating remotely from other US states and other countries. Our goal was to produce and publish a manual for the Firefox browser in two days.

After participating in the book sprint and using the FLOSS Manuals TWiki publishing platform, I am now a wiki publishing convert. Granted, a true, complete publishing solution takes quite a bit of customized development, but the FLOSS Manuals platform exemplifies the possibilities.

The FLOSS platform encourages topic-based writing. It has a simple user interface for writing and editing. It enables participating writers to remain aware of the status of big-picture content development at all times. As a participant, you can chat with remote writers. You can observe the state of in-process topics (such as needs updating, to be proofed, or complete). You can save your work and resume later, or another writer can step in and complete the topic.

We used Firefox help topics as source material, with the goal of improving the structure and the content. We wrote. We edited. We held group discussions. We had direct access to Firefox expert Chis Hoffman of the Mozilla Foundation. Chris was on site with us in Rancho Mirage.

At the end of the sprint, we all gathered to watch as FLOSS founder Adam Hyde walked us through the publishing process. Seeing the result of our work published in real time was exciting. The platform does an amazing job of paginating, and it includes headers, footers, and page numbering. It also enables you to “remix” a book’s content and publish your own customized version. You can buy published FLOSS books from the FLOSS Manuals storefront at lulu.com. The proceeds help to further the work of the foundation.

Here’s a picture of some the writers who participated on site at Rancho Mirage.

Left to Right: Adam Hyde, Me, Greg Urban, Jay Maechtlen, Chris Hoffman, and Janet Swisher (Photo courtesy of Greg Urban)

Remember, you can participate in a FLOSS Manuals book sprint without attending in person. You can join as a remote participant. By helping to create documentation for free, open-source software, you can help encourage more people to use the software. If you are interested in participating in future sprints, you need to register on the FLOSS Manuals site.

Fellow blogger, tech comm expert, and FLOSS Manuals evangelist Anne Gentle expresses exactly why I found the sprint so amazing:

A book in two days thanks to a great group of writers, an excellent Subject Matter Expert, and remote contributors from Calgary to Moscow to Bangalore.

You can visit Anne’s blog to read her full summary of the event. Then join FLOSS Manuals and have some fun.

Back to top

For the last 2.5 years, I have had the honor of developing content that supports cancer research. I developed various guides, online help, and a training course for the National Cancer Institute Center for Biomedical Informatics and Information Technology (NCI CBIIT). My audiences included ontology editors, software developers, administrators, and grant managers.

I found my work with the Enterprise Vocabulary Services (EVS) group especially rewarding. The EVS is a subset of NCI CBIIT. The primary mission of the EVS is to “harmonize and integrate the many diverse terminologies and coding frameworks used by the NCI and its partners.” The group works with research institutions in and outside of the United States to promote collaborative terminology development. Their technical infrastructure includes the NCI Thesaurus and other terminology databases. My work supported the development and maintenance of that infrastructure.

The EVS also introduced me to the world of wikis. If you have no idea what a wiki is, you can learn more about wikis at Wikipedia.

Make Wiki, Not War

Before working at the NCI, I had no direct experience with wikis. The software developers at a previous job had set up a wiki using the “build it and they will come” principal, but no one led the effort. The wiki eventually languished.

I had also come close to working on a wiki-based project while consulting with a large service organization to develop a centralized knowledge base. Various factions were at odds about whether to use a proprietary database or an open-source wiki solution. A particularly influential business unit was lobbying to deploy the wiki, but the management team was against it. Management was wedded to their solution and made no effort to understand wiki technology. They simply asked me to step in and explain to the sub-group why a wiki wasn’t appropriate.

Because I had so little knowledge of wikis, I wanted to do research before getting involved in the discussion. I asked “shouldn’t we all become more educated on the subject of wikis before we dismiss the idea?” But the managers wouldn’t hear of it. They had heard too many stories about wiki anarchy and loss of control. Ironically, after doing the research, I was convinced that a wiki might be a better choice than the proprietary solution. After failing to change the minds of the naysayers, I managed to extricate myself from the political crossfire.

The Wisdom of Wiki-Building

The NCI CBIIT experience gave me my first real opportunity to develop content in a wiki environment. In early 2008, the organization implemented a wiki for project management, process management, and resource sharing. Long-time STC member and wiki expert Ann Wiley was the site architect and mentor. In addition to other daunting tasks, she built an online catalog of our sizable documentation library.

I began to appreciate the power of wikis as a versatile tool for organization and knowledge sharing. I could see daily details of projects to come. I could instantly post a live information plan, share it, receive notification of comments, and update it. No more circulating Word documents and waiting for review comments. The wiki gave new meaning to the concept of a “living” document.

Later in the year, the EVS launched the BiomedGT wiki to support the development of the Biomedical Grid Terminology, “an open, collaboratively developed terminology for translational research.” The wiki promotes collaboration from terminology experts in the scientific community, though it’s hardly the renegade monster that my other clients feared. Anyone can browse and search the terminology, but they cannot create a login or edit the terminology without first undergoing a screening process. Interested collaborators must submit their contact information and credentials, be approved, and receive a login from the wiki administrator.

Even after passing the screening process, approved BiomedGT wiki collaborators cannot directly edit the terminology. Instead, they suggest changes by submitting “proposals” using online forms. Those changes can range from retreeing a term (moving it to another position in the hierarchy) to deprecating a term.

At the point of submission, a proposal enters a workflow process where it interfaces with internal NCI editing tools. The most notable of those tools is NCI Protégé, a version of the open-source, OWL-based Protégé ontology editor developed by Stanford Medical Informatics. While NCI editors review the proposals and “curate” the vocabulary, outside collaborators can use the wiki to trace the proposal status.

I contributed to the BiomedGT wiki by editing and restructuring information, writing help pages, and adding CSS flourishes. I found the work liberating, because the focus was mostly on writing and content. Wiki markup is easy to learn, and wiki templates are a great mechanism for content reuse.

Wiki out West

Next week brings a new wiki adventure. While attending DocTrain West in Palm Springs, I will participate in an event called Firefox Book Sprint: From Zero to Book in Two Days. We will use the FLOSS Manuals toolkit, a collaborative wiki writing environment, to create a new manual for the Firefox browser.

I first learned about FLOSS manuals and met its founder, Adam Hyde, at DocTrain East in October 2008. FLOSS Manuals is a not-for-profit, volunteer-based foundation based in Amsterdam. FLOSS stands for “Free, Libre, Open Source Software,” and its volunteer writers collaboratively write documentation for free, open-based software. FLOSS writers also wrote the help content for the One Laptop Per Child program. I am excited about the opportunity to be a part of a Book Sprint.

Related Links

This section provides links to everything that I have discussed in this post.

• Learn more about the NCICB
• Learn more about the EVS
• Visit the BiomedGT wiki
• Learn more about the Protégé ontology editor
• Visit the FLOSS Manuals site
• Learn more about the One Laptop per Child program
• Learn more about the Firefox Book Sprint at DocTrain West

Back to top