Gilbane’s Digital Experience Conference program live

Gilbane’s Digital Experience Conference program and registration are now available at digitalexperienceconference.com. Conference tracks Digital experience technologies for customers and the workplace Focused on what you need to know about evolving, and potentially disrupting, content and digital experience technologies for marketing and the workplace. We’ll be looking at what web and data analysis technologies are […]

This post originally published on https://gilbane.com

Categories: DITA

Orbis Technologies Acquires Turn-Key Systems

Really Strategies - Mon, 2019-01-14 20:04

(Annapolis, MD) - Orbis Technologies, Inc. has completed the acquisition of Turn-Key Systems Pty Ltd, an Australian software company. Turn-Key has over 20 years of experience in the content management market and holds an impressive client list of companies located in Australia, Europe, the United States, and Canada.

Categories: DITA

GitHub Pro account or GitHub Free account for Technical Writing

JustWriteClick - Mon, 2019-01-14 11:44

Should I downgrade or upgrade my GitHub account, now that the free tier has unlimited private repositories? I could save seven dollars a month, 84 dollars a year.

I looked into this question for myself, and didn’t get enough info from the pricing page at github.com/pricing when the change was first announced. So, I logged a help ticket with GitHub, and as I’ve experienced before when I was working on the Docs Like Code book, they were very responsive! I had an answer by the next morning in my inbox.   My specific question was, “What are ‘advanced code review tools,'” quoting from the pricing page. I must note: the great thing about asking this question is that I see that the pricing page now points to the answer to the question! The link is now available, and the text has changed to “Advanced tools and insights.” My inner product manager heart jumped with glee.

What do you get with the GitHub Pro Account?

What I learned is that the added features are related to many things that are useful for doc publishing and reviews, using private repositories on GitHub. These features and tools on your private repos include these, with links to help pages where available:

Now, you can do all those things on public repositories with your GitHub Free account. So what does this mean for people using GitHub for tech writing? I think it’s similar to any use case for development. If you want to work in private with more than three collaborators, and publish from a private repo to a public webpage using GitHub Pages, you want a GitHub Pro account. If you’re pretty sure you’re always going to work in public repos in the open, then you don’t lose anything by staying with a Free account.

For me, I’ll keep paying my $7 a month as I’ve found it super valuable to work through things either on my own or in small groups. I also like protected branches, sometimes for my own safety. And maybe, or at least I’d like to think so, I’m supporting students and starting users of GitHub by supporting GitHub itself.

Categories: DITA

Startup costs for writing a book on GitHub

JustWriteClick - Sat, 2019-01-12 12:13

What does it take to put together a web site, a book, an ebook, all for sale online? Let’s look at costs for tools and services that make it happen.

Let’s look at what you need for a book idea. You need an audience, an editor, a way to reach that audience, and a “pitch” for the book idea itself. You may chose self-publishing over pitching the book idea to a technical book publisher.

In my recent experience with Docs Like Code, the process led me to choosing to produce the site, epub, and printed book all using tools I had prior experiences with. Let’s take a look.

Reaching out to current contacts

First, I reached out to Andy Oram, a senior editor at O’Reilly who knows me from a couple of open source projects, asking if he thought O’Reilly would want a book proposal. He said he’d be happy to read what I had, but didn’t see the initial concept fitting into their current catalog. Really great of him to offer to help out, and I simply thanked him and kept going with my idea.

In parallel, I reached out to the publisher for my first book, Conversation and Community. His name is Richard Hamilton and he runs XML Press. When he looked at his schedule, he couldn’t read through at the draft copy for about 3 months. Well, I thought that the timing was essential, and I didn’t want to wait that long, knowing both the market and my own availability.

Finding like-minded collaborators

I also reached out to Diane Fleming, now Skwish, who had been teaching writers how to use Git and GitHub for docs over the same time as I had been. Over lunch, we realized we both wanted this book to be available for the next time we teach developers and writers how to write and review docs on GitHub. Diane is a talented writer and also a super editor. The best writers re-write a lot, and I knew Diane would provide an eagle eye for both technical accuracy as well as great writing.

Then, I realized I have a great friend in Kelly Holcomb, who edited my first book and I could talk her into editing this one, wahoo! Kelly also had experience in using GitHub for editing, so her contributions were super important for the final copy.

One area I did skip on for this book was a professional-level index, which Kelly was able to do for a great job on for Conversation and Community. I haven’t missed the index yet, and for a smaller book it seems like an index could look like padding.

Design materials and promotional work

I also was able to do all the design imagery myself, including the book cover. This part was thanks to Canva and some nice templates that service has online. I used the free trial for Canva to make the book cover and stickers and t-shirt design.

That said, I was not willing to take on the layout work myself. So, when Gitbook did not output a PDF that I considered “print-ready”, I went to Upwork. I wanted more fine-tuned layout and design for the print copy, including proper page breaks and nice tables. So I hired a designer with access to Indesign who could take the epub and turn it into a print book.

Pull it together!

And so, with all those bits of input from others, it created a quest to be a product manager for my own information product! I went that route, and for me, Lulu was a tool I was already familiar with because we had done publishing with it for OpenStack.

There are other publishing options – IngramSpark, Amazon, LeanPub, and I’m sure others. I did sign up and get approved for an account with IngramSpark, which is the print-on-demand service that XML Press uses.

To me, after reading the origin story for Lulu, I feel that Lulu is a bit more “open source” based than say, Amazon. I don’t know much about LeanPub. Since I was using Markdown on a private GitHub repo anyway, it doesn’t seem to offer more than Lulu for the marketplace reach. I’m not trying to make money at it; only trying to increase reach.

Finding a freelance editor would be a huge leg up on the writing process itself, especially if you also need a bit of developmental editing for the book idea.

For the print layout, I had a great experience with UpWork and was also able to keep the same person for work I needed one for the second edition. I learned from using a freelance site that I can find and manage freelancers for projects that I want to get done but don’t want to carve out time or buy tools for myself to finish them.

List of tools and services


Ongoing and startup costs

Here’s a high-level overview of the startup costs for creating a book like Docs Like Code. I calculated the starting costs for six or five months, when I needed a monthly subscription for a service.

Based on Lulu reporting, I see the book brought in about $2500 in 12 months of the first and second edition being available. So while the startup costs are not nothing, I did see a profit from the effort. Really, though, the effort is paid off in helping others see the benefits I’ve observed and in sharing and learning. Let me know what you think about this method, the tools, and of course, the resulting book, Docs Like Code, which you can buy online.

ServiceCostsDomain name registration$20/yearGitHub for Private repo$42 ($7/month x 6)GitBooks for Private repo$35 ($7/month x 5)GitHub Pages for website$0Canva for Work (cover art)$0 trialLulu (printed copies)$82 for 15 printedEditing/Writing$250 celebrationDesign for PDF layout$250MailChimp (ongoing)$42 ($7/month x 6)Twitter ads$25 for adsStickers$82 for 200Total startup costs$828

First published on Docs Like Code at https://www.docslikecode.com/articles/practical-advice/ in April 2018.

Categories: DITA

Gilbane Advisor 1-7-19 — Open gov data, AGI, analog revolution, future book

Happy New Year Dear Reader! We’re back from our holiday break. Though we don’t publish in December we do continue to read and select trustworthy content worthy of your valuable time. Enjoy. Congress votes to make open government data default in U.S. Surprise! “On December 21, 2018, the United States House of Representatives voted to enact H.R. 4174, the […]

This post originally published on https://gilbane.com

Categories: DITA

Hone your writing skills or specialize? Observations from 2009

JustWriteClick - Tue, 2019-01-01 13:14

Never permit a dichotomy to rule your life, a dichotomy in which you hate what you do so you can have pleasure in your spare time. Look for a situation in which your work will give you as much happiness as your spare time.

Pablo Picasso

Someone pointed out a bit of a dichotomy in technical communication the other day. It was such an interesting observation that I’ve been thinking about it for a while. The dichotomy is between the power of plain old writing skills and the power of “sexier” specialized skills.

What are the specialties?

Directions for tech comm that  Tom Johnson and Alan Porter discuss on their respective blogs is a movement towards videos and screencasting (screencasts category on Tom’s blog) or graphics and illustrating (comics category on Alan’s blog). Updated to add: One that seems to be standing the test of time is the Google Chrome comic.

Mostly these posts talk about how users don’t read the manual (which is okay, in this post by Tom Johnson). Perhaps specialization is a wise direction to take, because specialization may not be taken over by “the crowd” as easily as writing. WordPress.tv, for example, was seeded with 20 professionally-produced how-to videos, and the community can add videos to the site as well. You can mostly detect which were made by professional film-makers, so it would appear they’re employable longer.

Content farms go moo

Since anyone can write, and content farms are impacting the web, filling it to the brim with quickly written, search-engine baited fast-food content, hone more specialized skills in order to thrive in the shifting sands of the web, right? However, content experts like Brian Massey say that all content, no matter the source, is what’s driving the successful websites and web applications today. The written word is still effective with measurable results, and is overwhelmingly more prevalent on the web today, page for page. Mint.com, for example, is a wonderful redistributor and aggregator of banking and investment accounts, a specialized type of content. Mint also creates content, such as the weekly summary newsletter, that encourages you to return to the site. This content is text and numbers, with lovely graphs, but it’s really the numbers that shine.

To summarize

With both sides pointed out to me now, I’m leaning towards the broader content strategy movement. I will help people get content from any source, even if it’s built by a community or (gasp) ordinary users. But I do see the value in video and especially in non-text-heavy mobile content as we roll into the new year and a new decade.

Here’s my observation. If it’s true that bit.ly, the link shortener that’s popular on social sharing sites, has counted over a billion click-throughs per month, then it’s possible that social sharing will overtake search engine optimized content. As noted in 5 Trends That Will Shape Small Business in 2010, “Social search has the ability to eclipse the value of traditional SEO efforts.” A comment counters with the trend to go from text to video, saying clients should “record, record, and then record some more.” (Updated to add: This is certainly true, nine years later, though unexpectedly to the detriment of the internet as a whole.)

Let me repeat that. Eventually there could be more people reading and clicking through links on social sites than searching and clicking through links in search results. How will that shift change how you create content, and how will you strategically choose the content that you create?

I know the choices I have made in the last decade that have set me on the path of specialization, including community-sourced content, open source methods, and developer documentation including API specifications.

Originally published in December 2009, updated December 31, 2018. I think my favorite line is “Content farms go moo.”

Categories: DITA

Playing with wdtaxonomy

bobdc.blog - Sun, 2018-12-23 14:51
Those queries from my last blog entry? Never mind! Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Digital Experience Conference Holiday Discount

Save Up To $400 Until December 31! Before you head out for the long weekend, take a moment to register for Digital Experience Conference and take advantage of our Super Early Bird savings of up to $400 off the regular rate of our most popular conference passes. The program will be available soon, but you have […]

This post originally published on https://gilbane.com

Categories: DITA

Orbis Technologies wins DoD Contract for Innovative Security Solution

Really Strategies - Wed, 2018-11-28 20:07

(Annapolis, MD) On November 1st, 2018, Orbis Technologies, Inc. was awarded a contract from the Department of Defense (DoD) to deliver an enterprise level automated security workflow and universal sign-on solution. This marks yet another major contract award for Orbis this year.

Categories: DITA

RSI Content Solutions India Opens New Office

Really Strategies - Tue, 2018-11-27 16:39
RSI India new office opening

Chennai, India – On November 8th, RSI Content Solutions India (RSI Content Solutions India Pvt. Ltd.) opened their new office location in the Chennai Technology Corridor. On hand from parent company Orbis Technologies were Brian Ippolito (CEO), Thuy Pisone (Corporate EVP of Global Services), and Kevin Chasse (RSuite Technical Director).

Categories: DITA

Extracting RDF data models from Wikidata

bobdc.blog - Sun, 2018-11-18 14:41
That's "models", plural. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Gilbane Advisor 11-15-18 — Design value, pencil vs mouse, mobile apps future

Business value of design Some welcome help for those of you struggling to justify the effort, and cost, of good design. We tracked the design practices of 300 publicly listed companies over a five-year period in multiple countries and industries. … Our team collected more than two million pieces of financial data and recorded more than 100,000 […]

This post originally published on https://gilbane.com

Categories: DITA

Empower Your Team to Write with One Voice While Still Sounding Like Themselves

The Content Wrangler - Thu, 2018-11-01 17:00

The trouble with companies is that they’re full of people, and people insist on having separate personalities and distinct voices. So it’s no wonder that issues of consistency and tone of voice creep into our conversations when we take an honest look at our content.

In my Content Wrangler webinar Empower Your Team to Write with One Voice While Still Sounding Like Themselves delivered on Nov. 15, 2017, I discuss the role voice plays in unifying a company’s content strategy. I give suggestions for how you can build a brand voice without sacrificing the individuality of the content creators on your team—including a simple, fun exercise.

Read on for some highlights from my talk, including answers to these questions:

  • What does “voice” mean?
  • Why define your brand voice?
  • Who needs to use your brand voice?
  • How do you define your brand voice?
  • How can your writers still sound like themselves?

Or go to the webinar, and listen to the whole hour’s worth for free.

What does “voice” mean?

For a business as for a person, your voice (aka tone of voice) is how you sound, who you are, what you stand for, and how you interact with people as conveyed in language. When your voice is unmistakable, the way a personality is unmistakable, people recognize you not just by what you say but also by how you say it.

Elements of voice:

  • Word choice
  • Word order (syntax)
  • Sentence length
  • Punctuation
  • Metaphors

Basically, every choice you make with language—whether or not you make those choices intentionally—contributes your voice.

For example, if your brand voice is friendly, upbeat, and casual, you might use the occasional exclamation point. (I could do that right now!) If your voice is more formal, you would stick with periods.

When your company’s voice is distinct—that is, when everyone producing content for your brand is speaking with the same voice—your audience will say (as Ahava Leibtag said to Ann Handley last year in her Content Marketing World talk), “I read a piece of content of yours and within two sentences I know you wrote it.”


Or… Cool.

Or… Damn cool!

(Would you say “damn” in your company’s customer-facing content? Would you use an exclamation point? If you don’t know, your company needs to define—or better communicate—its voice.)

Why define your brand voice?

You define a brand voice for several reasons:

  • It gives content creators more confidence.
  • It gives customers more consistency.
  • It gives the company more credibility.

Think of a brand that you love. That brand has some kind of voice that resonates for you. You see something from that brand, and you instantly have a connection to it as though it’s a friend. You have a sense of who is talking.

How can customers love you if YOU don’t know who you are?

Consequences of an undefined voice:

  • Confusion (internally and externally)
  • Brand erosion
  • Slower time to market
  • Costlier, less accurate translations

How do you quantify the benefits of defining a corporate voice? One way is to survey companies that are doing it. Acrolinx, for example, surveyed over 200 content professionals in companies that manage their terminology. (For their full report, see Terminology Management: How Companies Use the Words and Phrases That Matter Most to Their Business.) The top reasons respondents cited for managing terminology were “to ensure correct usage” and “to help enforce style and tone of voice guidelines.” And the top benefits they cited, as shown in this chart, were “more consistent brand voice” and “less confusion within tech docs due to inconsistencies.”

Who needs to use your brand voice?

All content creators in your company, including people creating presale and postsale content, need to use the same brand voice. In fact, the presale-postsale distinction is false. Some companies find that documentation brings in over 50 of their qualified leads. So documentation often IS sales literature.

In other words, all content that customers see needs to follow the corporate voice guidelines.

Why would you want to talk differently after the sale anyhow?

How do you define your brand voice?

You can define a brand voice however you like. Many companies choose a handful of adjectives, that is, describing words, such as “reliable,” “thorough,” outrageous,” and “funky” (not that you’d ever find those four words together in the same company’s voice description).

Avoid meaningless adjectives, such as “cutting-edge,” which are so overused as to be unhelpful. Some people call these cotton-candy adjectives because they’re full of air and lack substance.

Your voice adjectives aren’t meant to go in the content itself. They’re for internal reference; they support writers in making decisions about customer-facing content.

List your adjective in this-not-that pairs

One way to make your set of adjectives especially useful is to put adjective pairs in a this-not-that structure. This structure gives writers sort of bumpers. Limits. What to do—and what not to do.

Example from the Content Marketing Institute voice guidelines:

  • Authoritative but not pompous
  • Approachable but not wandering
  • Informative but not academic
  • Quick-witted and relatable but not corny
  • Entertaining but not inappropriate

Example from the MailChimp voice guidelines:

  • Fun but not silly
  • Confident but not cocky
  • Smart but not stodgy
  • Informal but not sloppy
  • Helpful but not overbearing
  • Expert but not bossy

Try sorting cards

Some companies, in defining their voice, find it helpful to use a deck of adjective cards, such as Margot Bloomstein’s BrandSort cards, to prompt conversation between stakeholders. One common approach is to sort the cards into three piles:

  • Who we are
  • Who we’re not
  • Who we’d like to be

The steps ideally go something like this:

  1. Pick a leader.
  2. Prepare a set of adjective cards.
  3. Gather stakeholders.
  4. Sort the cards. DEBATE!
  5. Document your choices.

This exercise’s value comes not simply in arriving at a final set of words but in having a rich debate, tussling over which adjectives fit or don’t fit your company, learning why your colleagues prefer certain words over others. A lot goes into a successful card sort of this kind. If you want to give it a try with your own team, check out my detailed write-up based on Margot’s methodology: Use This Simple (& Fun) Tool to Design Your Content Marketing Message Architecture.

How can your writers still sound like themselves?

After you’ve defined a brand voice, you’re ready to share them with your content creators. To supports writers in writing with one voice while still sounding like themselves, provide a combination of guidelines and examples.

Here’s a model from GatherContent (from their article A Simple Tool to Guide Tone of Voice):

This model includes four components, each shown in a circle: an adjective (“personality trait”) that describes your voice, one positive and one negative writing example, and the rationale for this choice.

Following this model, here’s what the writing guidance might look like (again borrowed from GatherContent):

Concrete how-to guidance like this gives a team of writers a sense of what everyone’s content should sound like without being overly restrictive.

Watch the full webinar

For the rest of what I had to say on this topic, watch the full webinar here.

The post Empower Your Team to Write with One Voice While Still Sounding Like Themselves appeared first on The Content Wrangler.

Categories: DITA

SPARQL full-text Wikipedia searching and Wikidata subclass inferencing

bobdc.blog - Sun, 2018-10-28 16:37
Wikipedia querying techniques inspired by a recent paper. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Gilbane Advisor 10-25-18 — flat world, infrastructure app cycle, digital archives

Internet, social, device growth flat in U.S. Certainly not news to suppliers of these technologies and services, and unsurprising to others. But this is just the kind of trend that is so obvious the reach of the repercussions can easily be overlooked. Any business that, even indirectly, depends on these products for growth, needs to assess how the saturation effects their product and […]

This post originally published on https://gilbane.com

Categories: DITA

Orbis to Showcase RSuite® and DocZone™ at 2018 Frankfurt Book Fair

Really Strategies - Thu, 2018-10-04 20:28
FBF 18 banner image

Annapolis, MD – Next week, the Orbis Technologies, Inc. team will make their annual journey to the Frankfurt Book Fair in Germany. New for 2018, both of Orbis’ CMS software products will be featured: RSuite and DocZone. The products will be presented side-by-side, as two distinct options for companies with publishing and content management needs.

Categories: DITA

Panic over "superhuman" AI

bobdc.blog - Sun, 2018-09-23 15:27
Robot overlords not on the way. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Every DITA topic should be able to fit anywhere. (Not really.)

Geekery - Sat, 2013-10-12 17:05

When I talk to writers about this, I state the case strongly: every topic should be able to fit anywhere. That always provokes some pushback, which is good. Of course it’s not really so, in practice. There are many combinations of topics that are just never going to happen. However, on a large scale, with hundreds or thousands of topics, there are many, many plausible combinations, some of them completely unexpected.

In fact, there are so many plausible combinations, you might as well not worry about the impossible ones. You might as well just go ahead and write each topic as if you had no idea what parent topic it was going to be pulled into.

That’s what we mean by “unleashing” your content with DITA. It’s the combinations of topics that bring the value, not the individual topics themselves. If you draft each individual topic so that it’s eligible for the largest possible number of combinations, you’ve multiplied the usefulness to the user (yes, and the ROI, and the technical efficiency) of the information in that topic. For any given topic, it’s true, there may be only three or four conceivable combinations in which it could make sense. For some, there might be hundreds. You’re not going to know unless you write for reuse in every case.

Once we’ve put this into action, we can go back to the managers and gurus and say, now you’ve really got ROI; now you’ve really got efficiency. Because we’ve given you something that is worth investing in, something that’s worth producing efficiently. Something that can delight readers with its usefulness and its elegance. This isn’t just content, this is writing.

Categories: DITA

DITA makes it possible for any information set, no matter how complex and huge, to be represented with a single page.

Geekery - Tue, 2013-10-08 00:33

In any information set, every component should be able to roll up into what is ultimately a single top-level summary. We know most readers don’t come in through the front door, but in principle you can provide the reader with an entry point that fully sums up what’s in the information set. From there they can drill down into more and more detailed levels. (Readers can be very easily trained to do this, because they have learned from their previous reading to scan for summary-like information and use that to judge whether it’s worth reading on for more detail.)

If each level is itself a rolled-up collection of subordinate units, and so on in turn down the ranks, what you are offering is a set of pages in which each page is itself a table of contents. The content is the navigation and the navigation is the content.

Picture this single page sitting at the apex of a pyramid. It contains (describes) everything that is included in that pyramid. Not that many people are ever going to actually read that page, but we need it to be there, because it defines the pyramid.

The bigger the pyramid, the higher level the information in its top node is going to be. So, for a very large information set, that single page is going to be very general. Each of its immediate child pages will be a level more detailed, and each successive level is going to be more detailed, until you get to the bottom “leaf” level where a topic describes only itself.


Categories: DITA

Modularity is what makes it fun to write with DITA.

Geekery - Tue, 2013-09-24 19:13

The most disorienting thing about learning structured writing is modularity. There are a lot of things we’ve learned about writing that we have to unlearn; this is the most fundamental of them. This is way bigger than deciding it’s OK to dangle a preposition.

Modularity means, in practice, conveying meaning in free-standing chunks instead of in a unified stream. Why is it so great to be free-standing? What does that get me, from a purely authoring perspective? (Remember, we’re still excluding managerial and technical perspectives from this conversation. You folks can come on back later.)

In mature DITA writing, many topics are built up automatically from component topics. Done well, these composite topics look like you lovingly handcrafted them with sections, section titles, section detail, overview material, and so on. In fact, you threw them together on the fly from component topics that you happened to have lying around.

How good your built-up topics are depends on how good those component topics are. How good the components are is largely a function of how well each one delivers meaning on its own, without having to wait for any other component to its job.

A composite topic that looks and reads like a composite topic is a failed composite topic. It needs to look and read like it was specifically conceived for this particular user at this particular moment. We want its component topics to match, in tone and style and scope, so well that they look like they were all written at once for this specific collection.

You’re working on a building, from the roof down and from the foundation up at the same time. You know what you need your built-up composite topic to do, which influences how to you’ll define and select or draft its component topics. At the same time, as your component topics come into being, they’ll influence the scope, scale and ultimately the effectiveness of the composite topic you’re building from them. In my experience, it’s when this process gets rolling that you really start to feel like you’re doing interesting, useful writing. This is where the fun starts.

Categories: DITA
XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I