DITA (Darwin Information Typing Architecture) is a versatile and widely used standard for content creation that is usually implemented using an XML editor. It is a structured authoring standard, or framework, that separates content and format. One of the major characteristics of DITA is that the smallest unit of content is a “topic”. A DITA topic is freestanding, reusable content that is focused on one specific subject. Standard DITA topics are categorized into three information types: concept, task, and reference. The process of dividing topics into categories based on their content is referred to as “information typing”.
Concept, Task, and Reference Topics
Each topic has one specific goal based on its information type:
Concept topics help the user understand an idea or the purpose of an instruction. They often provide the user with background information that they will need before they begin a task. An example of a concept topic is an article explaining a new type of computer program and its features.
Task topics help the user to do something, typically with step-by-step instructions. Task topics typically use numbered lists to present instruction steps. An example of a task topic is a set of instructions on how to build a new chair.
Reference topics give the user descriptions about something without explanation. This differs from a concept in that it does not require the reader to totally understand something; it is more concerned with providing them with facts. An example of this is the nutritional information for a beverage. Often this information is presented as a table.
Each information type has a standardized structure to serve its purpose. Because each topic has its clear and distinct goal and structure, it is easy for a user to find the exact information they need. This is what makes content accessible and usable.
Using DITA topics has many benefits. Some of the most valuable are reusability, scalability, and consistency. DITA structured authoring creates content that can be understood as standalone topics or within a larger context. One DITA topic can be reused for multiple publishing outputs, so there are no similar but different topics that could propagate discrepancies or inaccuracies through future edits. Content reuse, also known as single-sourcing, enables a change in one topic to be reflected in all the publishing outputs. DITA’s predefined structure allows the author to focus on the content itself, while still maintaining a consistent structure.
Resource for Learning More
Topic, Concept, and Reference are the most widely recognized DITA information types. There are also other types of DITA topics that have different standards and goals than the topics listed above. You can learn more about the other kinds of DITA topics, as well as how to use them, by signing up for a free course at Learning DITA.These courses will give you a better idea how DITA topics present content in real-world settings.
STC Toronto are thrilled to announce the upcoming launch of the newest iteration of our Job Bank! We’ve been working on it for several months and we are now working on final preparations for our launch. We’ve redesigned it from the ground up and built it on WordPress to take advantage of all the functionality and security this platform provides.
Here’s a peek at you can do with the new Job Bank:
View all listings
View all current job listings on a single page.
Filter jobs by Contract, Permanent, and other gig types.
Search for what’s important for you.
Search by keyword, location, and more.
See job locations on a map.
Save jobs you’re interested in and look at them later.
Apply for jobs.
Now you can apply for the job directly from the job listing!
Post Your Resume
Create your own online resume.
Employers can search by keyword, skill type, location, and more.
Apply to jobs directly from the job listing by sending along your online resume.
Best of all, use of the new Job Bank is included with STC Toronto membership! Members don’t have to pay anything to use it as long as they maintain their STC Toronto Chapter membership when they renew their STC membership.
How do I get access to the new Job Bank?
We will send STC Toronto members an invitation by email very shortly. When you receive this email, be sure to click the link to set up your account and choose your password. Then watch for the confirmation email, and you’re good to go!
If you’re not a member of STC Toronto, you can buy an access pass just to access the new Job Bank. Prices will be available on the new Job Bank when it is launched.
We think you’ll enjoy all the new functionality available in our new Job Bank.
Kay is an accomplished technical communicator with over 12 years’ experience documenting hundreds of technical processes, training others to duplicate results, and helping beginners find their bearings in the world of technical communication. Kay fell in love with technical communication, as it combines her twin passions –English language and Technology.
Currently, Kay is a Content Specialist at Precision Content Authoring Solutions Inc., a full-service solution provider to medium-and large-scale organizations around the globe seeking help to better understand and solve their content challenges. Before joining Precision Content, Kay led successful technical writing and training deliveries in several startups and multinational companies, across industries including software, finance, telecom, and healthcare. She also spent nearly a decade with IBM as a senior information developer, helping IBM’s clients solve their documentation and training challenges.
Kay’s personal style is to lead by example, always doing her best and encouraging others to do the same. She uses her positive attitude and tireless energy to encourage others to work hard and succeed. She strongly believes that the best way to ensure the growth of the field of technical communication is for the community to help each other learn and grow. You can accomplish such knowledge sharing, only if you really connect with people and communicate your understanding to them.
While she enjoys a good Netflix binge, Kay also loves to unwind with a warm cup of coffee and a good book. On somedays, she can be found enjoying a quiet stroll with her husband in the parks and promenades of her neighborhood.
Kay earned her MA in English Literature from Christian College, Lucknow University.
The term microcontent originates from usability advisor Jakob Neilson, as he coined it in an article in 1998 (Neilsen & Loranger, Microcontent: How to Write Headlines, Page Titles, and Subject Lines). The term has been adopted by many fields including technical writing, marketing, and UX/UI. The following article will explore the topic, its relevance to technical writing, and its prospective benefits to users and writers alike.
In a brief definition, microcontent can be described as “text, image, or video content that can be consumed in 10-30 seconds” (Lorrie McConnell, Microconent and What It Means for Communication and Technical Writing). While the amount of time it takes to consume media is important, it is not the only defining characteristic.
In addition to this, I would refer to a definition supplied by Rob Hanna (Supporting information-enabled enterprises: Reengineering for better flow with microcontent). He notes that microcontent is content that is
about one primary idea, fact, or concept
labelled for clear identification and meaning, and
appropriately written and formatted for use anywhere and any time it is needed.
Microcontent as a methodology of creating content has grown in popularity recently. It is a topic that is often associated with marketing and DITA authoring; however, the aforementioned definitions formulate microcontent as an approach that is widely applicable to different types of communications.
Why is microcontent becoming popular?
As all industries change because of technological advancement and cultural shifts, content is likewise changing. Content is being produced, maintained, disseminated, and consumed differently than it was twenty years ago. Users want to find and use information as fast as possible and are often not willing to navigate poorly designed documents. Technical writers need to adjust their content, their writing, and their technology to keep up with the new demands. Developments in chatbots, machine translation, and single sourced publishing demand new content formats that microcontent can provide.
Three benefits of microcontent
There are three characteristics of microcontent that benefit both the content creators and their users.
Microcontent requires that each block of content be focused solely on one idea and fulfilling one purpose. Unrelated content is either cut or moved into separate content blocks. The user spends less time navigating and reading, more time applying the information.
In the current digital landscape, the content’s searchability is a determining factor for the content’s usability. If information is not easily searchable it will not serve the users even if it is usable. Since the microcontent approach rigorously enforces the consistency of terminology and content labelling, precise search results can be delivered to the users. Users do not need to scan through irrelevant information to find what they need. In addition, this also helps technical writers to develop and maintain content throughout development cycles.
Users employ a range of reading strategies when engaging with technical documentation. Most reading strategies are not linear, as is detailed in Tom Johnson’s article on I’d Rather Be Writing (Johnson, How to design documentation for non-linear reading behavior). Users often search for a point of information and then branch to related queries. Microcontent’s molecular nature allows readers to easily find needed information and navigate to other related content. Each topic can contain links to related information and can be referenced in each file. Analyzing and predicting the user’s needs and search patterns is essential to creating a functional network of content.
Applying microcontent methodology
Creating well designed microcontent requires that information be
not reliant on external information
not reliant on circumstances
Consider this example: an electronics company is producing a line of keyboards. Each higher-end model retains the features of the model beneath it. The documentation department is creating the feature descriptions as microcontent which will be reused in each model’s documentation. This is a good example of microcontent because the content
focuses on one feature
assumes no context
is accessible, usable, and reusable
Well designed microcontent makes for well designed technical communications because it allows the users to reference information to a specific end. When an entire document is chunked properly and uses this format, it makes the document as a whole easier to scan and utilize.
Challenges to creating microcontent
There are difficulties in developing microcontent. Difficulties can arise from
chunking information properly
making content that is not dependent on context
These challenges can result in problems for writers as well as users. Chunking information can be difficult. Some topics are more contingent on supporting texts, circumstances, or settings, and writing them as isolated microcontent is no easy task. It can, however, be accomplished by strictly adhering to the topic format, wherein each block of content must serve one purpose, and then using links for references and related topics.
When technical writers reuse content that is not designed for reuse (which is dependent on circumstance or context), the users may find the information incomplete, inconsistent, or confusing. Furthermore, to design reusable content requires control over the project as well as the document’s continued adaptability to changes in product or services, which can require hours of labour to make corrections and to redraft content blocks. Anticipating and managing changes can pose a challenge to maintain the integrity of reusable contents.
Microcontent is a nuanced methodology for technical writers to produce content that is optimized for contemporary users and technologies. It creates a focused network of searchable writing for users and allows writers to create and maintain documents using the technological advantages of Content 4.0.
Technical writers already use many of the strategies that are employed in microcontent, however, they may not always do it with rigor. By adopting microcontent methodology, technical writers need to actively consider how information is chunked, grouped, and linked together, as a result, both users and technical writers will benefit.
Johnson, Tom. “How to Design Documentation for Non-Linear Reading Behavior.” I’d Rather Be Writing, Tom Johnson, 15 May 2015, idratherbewriting.com/2015/05/15/writing-for-users-who-read-non-sequentially/.
McConnell, Lorrie. “Microcontent and What It Means for Communication and Technical Writing”. Best Practices in Strategic Communication, 18 Apr. 2019, blogs.chatham.edu/bestpracticesinstrategiccommunication/2019/04/18/microcontent-and-what-it-means-for-communication-and-technical-writing/.
Explaining Season of Docs to family and friends was more difficult than it should have been.
Them: So… you’re working for Google? Me: No, I’m working for an organization named Oppia. Them: What’s Google got to do with it? Me: They organized the whole program. Them: Who’s paying you? Me: Google. Them: So… you’re working for Google?
‘Tis the Season
With the inaugural launch of Season of Docs in 2019, Google yet again establishes its passion for open source (Summer of Code being another one of their programs). The program aims to bring technical writers and open source organizations together so that both mutually benefit — writers gain open source experience under the guidance of mentors, and organizations benefit from improved documentation. Projects ranged from beginner’s guides and tutorials to API and reference documentation.
Season of Docs is aimed at early-career technical writers and I was fortunate it came my way just as I graduated from university looking for a career change. With some teaching experience in my arsenal, I was chuffed to learn that I was going to be working with Oppia — a learning platform focused on providing engaging content to students. I worked with Oppia on a standard length project (3 months) but longer-running projects (6 months) were also available — it all depends on the organization’s needs. Fun fact: Oppia is a Finnish word meaning ‘to learn’.
Meet the mentors
The period between I was first accepted into the program and the official start of the project was known as the ‘Community Bonding’ phase. This is how Google describes this phase:
Technical writers get to know mentors, get up to speed with the open source organization, and refine their projects in collaboration with mentors.
Sounds chill right? This is how my first meeting with Sean and Sandeep (my mentors at Oppia) went (and I’m obviously paraphrasing):
Them: Hey, so awesome to meet you, congrats, this is gonna be great!
Me: OMG I’m looking forward to this!
Them: So we’re actually revamping the entire software and the proposal you wrote is kinda obsolete, so do you want to learn all the amazing new features in the next two weeks and rewrite the proposal? And feel free to suggest a hosting platform to us, and also can you do some hallway usability testing to get an idea of how users would like to access the docs?
I personally called this the ‘Be cool and panic later’ phase. Of course, Sean and Sandeep were constantly available to assuage my fears answer any questions, so I never felt left in the lurch.
Researching a hosting platform was actually fun. A few popped up in my online searches but most required heavy use of the command line which freaked me out enough, I ran away screaming like a banshee. I finally decided to go with Read the Docs as it is the largest open source hosting site in the world — so I figured it was worth checking out.
Read the Docs generates documentation written in Sphinx. Thus far, my only association with that word was a certain statue in Egypt:
When I had no idea I would come across another Sphinx one day
I’ve since learned that Sphinx is a document generator used by the Python community. Writers use a lightweight markup language called reStructuredText (RST) or Markdown (or both!) to write the documentation. Of course I knew nothing about all of this at the time — and with that lack of knowledge, the official start of the project began.
Stack Overflow to the rescue
Writing was painfully slow in the beginning as everything was unfamiliar — the language, the command line, the Sphinx… Having weekly milestones helped as I could narrow down my focus to the task at hand and not be overwhelmed with how much I didn’t know. Stack Overflow was a godsend and I realized there were other open source newbies who had asked the same questions I did. I think I did more Googling than writing that first month. Seriously, what did we do before the Internet?
As the weeks went by, I fell into a rhythm as I got more acquainted with the world of GitHub and submitted pull requests with increasing confidence. I started to speak funny like, ‘Hey Sean and Sandeep, I amended the commit on that pull request, can you PTAL?’ (please take a look, duh.) I practically threw myself a celebratory party the first time I used git commands without referring to my notes.
What makes Oppia unique is that the platform lets you create explorations (lessons) that replicate a one-on-one interactive tutoring scenario. Most of my work involved playing around with the new dashboards and features, creating video tutorials and writing up the user guide. Every week or so, I would submit my completed work as a pull request on GitHub. Weekly meetings with Sean and Sandeep also helped immensely as the frequent communication made me feel very supported.
Building up Oppia’s documentation during Season of Docs
The second half of the project flew by and before I knew it, the guys at Google popped up again to sort out project finalization. Now Oppia’s software was still undergoing development and consequently there was more writing and video-making to be done — so we all agreed that this relationship was worth extending. Plus I was pretty excited about Oppia’s plans to have a wide international reach and I knew I wanted to stick around. So I barely noticed when Google announced the end of Season of Docs.
(Not) The end
Season of Docs is officially over, but my relationship with Oppia continues. I’ve since been introduced to other team members and I’m looking forward to contributing however I can. This to me is the major highlight of Season of Docs — the experience doesn’t have to end when the program does.
If you’re thinking of applying to Season of Docs in 2020***, go for it — and hopefully you will have an easier time explaining it to your folks. Connect with me on www.techwritingmatters.com or on LinkedIn.
***The editor’s note: The application for Google Season of Docs 2020 is closed. Please visit their official website for more information.
About the author
Audrey graduated from York University in 2019 with a certificate in Technical and Professional Communication. She is currently working as a technical writer at TAO Solutions Inc.
Technical Communication professionals have been talking about authoring in XML for a very long time. XML, a cross-platform markup language, was initially designed to meet the challenges of large-scale e-publishing. Were the challenges met? Did XML succeed in exchanging a wide variety of data on the web? Let’s discuss.
So, what is XML?
Extensible Markup Language (XML) is a cross-platform, software and hardware independent markup language derived from Standard Generalized Markup Language (SGML). It is purely a text-based technology with a self-descriptive language. The data in XML is structured using meaningful tags to specify a given set of information. It contains sender data, receiver data, heading, and a message body. You can add tag anytime to extend the content of the document thus making XML extensible.
An XML document also allows data storage in a format that can be interpreted by any computer system and hence it is used to transfer structured data between heterogeneous systems. It plays a very significant role in the movement of a wide variety of data on the Web.
XML is an international document standard created by the World Wide Web Consortium (W3C), an organization that is responsible for maintaining web standards.
Defining document content
While documenting in XML, you need to define the elements or define the structure that can appear in an XML document. This can be done by using DTD and/or XML Schema:
Document Type Definition (DTD): It describes the order in which the data should appear, how the data can be nested, and other basic details of XML document structure. DTD is part of the XML specification and works similar to SGML DTD.
XML Schema: A schema defines all the document structures that can be added in a DTD, defines the data types, and other advanced rules that a DTD cannot define.
An XML document with a DTD or an XML Schema is designed to be self-descriptive.
XML and HTML
We should note that XML is not a replacement of Hypertext Markup Language (HTML). XML and HTML were designed to achieve different goals.
XML was originally designed to describe, store, and transfer data. XML was not designed to display data. The tags are not predefined but are created by the author of the XML document. Whereas HTML was designed to display data in web browsers and the tags are predefined. When HTML is used to display data, the data is embedded in HTML format.
The XML files can be created and edited using a simple text-editor like Notepad. But professional XML editors help you to write error-free XML documents, validate the XML against DTD or a schema, and ensure that you adhere to a valid XML structure.
An XML editor should be able to:
Automatically add closing tags to the opening tags
Validate XML code
Verify XML against DTD and Schema
Color code the XML syntax to increase readability
Advantages of XML
Some of the advantages offered by XML:
Human readable content: The tags, elements, and attributes in XML files are not only computer readable but also can easily be interpreted by humans. This is the greatest advantage for writers who have limited knowledge of programming languages.
Domain-specific vocabulary: As XML does not have any predefined tags, it allows the user to create tags based on the requirement of an application. In other words, XML allows domain-specific vocabulary per the need of the application without any restriction on the number of tags that can be defined.
Ease of data interchange between computer systems: XML provides the structure for storing data in text format. It is used as a popular standard format for data interchange. Thus, differences in how systems exchange data become insignificant. It produces files that are unambiguous, easy to generate, and easy to read.
Better search engine performance: The XML file creators can inform a search engine that the search needs to be performed within certain tags. This allows a focused search. Therefore, using XML ensures the precision of the search result that matches the search query.
Separation of contents and formats: XML allows the user to implement conditional formatting for an XML document. A separate style sheet is maintained to format the XML document. XML uses two types of style sheets, Cascading Style Sheet (CSS) and Extensible Style Language (XSL), for formatting data. Because of this separation, it is easy to update and maintain the format of the document whenever required. Also, it is easy to maintain a consistent style sheet for all documents.
Granular updates: When data in an XML document needs to be updated, the entire page need not be reloaded from the server. Only the changed content is downloaded, thus making updates faster.
Flexibility: Writing an XML document is easy as compared to other markup languages. There are no predefined rules to follow, users can create their own tags and rules to serve their needs. So in terms of developing a document, XML is very flexible.
Multiple data types: XML documents can contain many data types which include multimedia data like image, sound, and videos. These multimedia data are embedded directly in an XML document as encoded text.
Easeof translation and publishing: When content is stored in XML tags, the cost of translations can be reduced by automation. It is much easier to translate an XML file because it allows content and format separation and it follows a rigorous standard and well defined syntax. Publishing the document in several languages can be done with a single click because formatting could be applied automatically while publishing source XML files.
Forward and backward compatibility: Forward or backward compatibility of XML files is relatively easy to implement: DTD and Schema allow tags to be defined as optional. As long as the newly added tags are descendants of the optional tag, the old and new versions are mutually compatible.
Why should we use XML in technical documentation?
A finished document can be assessed from two dimensions – effectiveness and efficiency. Effectiveness is whether the content clearly explains the product and the procedure to the reader. Efficiency is how quickly and efficiently the document was created.
We know that XML tags the elements of a document. For example, you use tags for a heading, a paragraph, and an item in a numbered list. As these tags help the rendering engine formats it appropriately for a wide range of output media, for content creators, the burden of formatting is reduced tremendously. Since the flexible tagging scheme helps to define the content and improve readability, many software engineers have been increasingly using XML as a means to document computer programs. We, Technical Communicators, also adopt XML for the same reasons.
When XML is suitable?
XML is especially suitable for documents with complex structures. Darwin Information Type Architecture (DITA) standards is a niche XML that is widely adopted in technical communications. DITA standards are written for different industries and different document types. Although DITA allows you to customize the tags as per your required style, customization is time consuming and costly. For structured documents that need more flexibility, XML is a good alternative.
Wide adoption of XML
As per W3C, XML is one of the world’s most widely-used formats for representing and exchanging information.
XML helps to represent, process, and exchange information with robustness and efficiency. Hence XML is heavily used as a format for document storage and processing, both online and offline.
Today, XML not only works with documents but also works with JSON, linked data, large databases (both SQL/relational and NoSQL), the Internet of Things (IoT), music players, in automobiles and aircraft industries. It is found almost everywhere.
Future prospects of XML in documentation
XML is a simple and very flexible markup language which will be a great foundation for many standards yet to come. XML also provides a common language that different computer system can use to exchange data with one another. Even when each industry group comes up with new standards for what it wants to communicate, computers can still exchange data with minimal barriers.
About the Author:
Sowmya is a Technical Communicator with experience in IT documentation.
STC Toronto chapter’s Annual General Meeting (AGM) was held successfully via Zoom on June 28th, 2020 amidst the COVID-19 pandemic.
The president and vice president of the STC Toronto chapter Joyce Lam and Shonna Eden co-chaired the meeting.
Looking back on 2019-2020
At the beginning of the meeting, Shonna presented the 2019 meeting minutes and looked back on events and activities held last year. The treasurer Vanitha Krishnamurthy then reviewed the chapter’s finances. Joyce followed by presenting the retrospection and outlook of 2019-2020. The focus of the council’s work was staying relevant, providing value for members by boosting the new job bank, increasing marketing effort and event attendance through strengthened online presence. Fostering the next generation of leadership for the chapter was also a top priority. Joyce also touched upon the challenges and opportunities presented by COVID-19.
Electing community council and executive council
After the retrospection, attending members elected the the new community council and Executive council.
The 2020-2021 community council
Job Bank Manger
Job Bank Coordinators
Kahkashan Kazmi, Michael Fowler
The 2020-2021 executive council
Presenting 2020-2021 action plan
Following the election, Shonna presented the action plan for 2020-2021, which includes:
Blend social and networking events with workshops and talks
Increase web presence of events
Complete the Job Bank renovation
Build partnership with recruitment agencies and colleges
Hold job fairs and career development workshops
After the formal agenda concluded, Joyce announced the various chapter awards given out at the end of 2019. Joyce also congratulated the Community Director Mona Albano and Treasurer Vanitha Krishnamurthy for receiving this year’s Community Service Awards from the STC head office.
For the grand finale of this year’s AGM, the renowned Canadian English expert and the former Editor-in-Chief of the Canadian Oxford Dictionary Katherine Barber gave the key-note speech on the history of the English language titled Why is the English Language so Weird? Filled with stories and fun facts, the talk garnered rave reviews from the attendees in the form of chat messages.
Press Enter to Continue is the clever title of a book written by Joan Francuz, a friend, colleague, former STCer and now author—in her own right, for what do we do, in our profession, but write books, tomes, pages, testaments and scripts of various sorts for our clients, just not for the general public in most cases.
When Joan autographed my copy of the book, she added “…and Ctrl S to save” after the title. That’s quintessential Joan Francuz and gives a taste of her witty style. While the book is historical—comprehensively so, but distilled to perfection—it is also chatty and full of personal treasures and stories too. In fact the book reads like Joan is talking to you, which makes it even more engaging. All of which makes this history of writing through the ages both personal and universal, as Joan discovers and exemplifies this “character trait—some call it a flaw—that compels people throughout history to sit down and write everything they know.”
And so it is that we learn of Joan’s love of gardening, her family, various jobs, travels and homes. But the meat of the book is the wealth of information on how scribes came to be and how they fashioned and used the tools of their trade through the ages.
With Joan’s deft touch and skill it all comes to life—from the Sumerians, to the Greeks, Romans, so-called Barbarians, and Renaissance men (I’m sure they had women too!); from symbols to characters to alphabets (first uppercase only, then lowercase) and the introduction of numbers and publishing; from all of these to the effects of religion, commerce, patents, railroads and more, including telegraphy and photography and how they influenced the dissemination of information. And all the while Joan relates to the material anecdotally, personally or with modern day comparisons. This is no dry history text!
A section entitled “Then people became data” introduces the digital age and brings us to “the time called now.” The book concludes with the thought that in every age people had a need to document the world around them. Press Enter to Continue carries on this tradition in exemplary fashion. It is a well researched piece of work documenting the history of our profession, with a bit of humour and personality thrown in for good measure. It is well worth the read!
Eliane Tozman is a Montreal-born, Toronto-based designer, currently working in UX Design (User Experience Design) at IBM. Tozman works in software development, where she researches, conceptualizes and designs ways for IBM to make the technology work for the user, so the user doesn’t have to work for the technology.
Tozman’s presentation focused on Designing for Disruptive Innovation and why it’s so important for creating successful outcomes. She provided insight and examples of how design thinking empowers multi-disciplinary teams to solve complex problems by considering many options, integrating ideas and opportunities, and testing multiple solutions before going to market.
IBM Design builds user-targeted products and experiences: this session offered an overview of this human-centered methodology. This method challenges people to see the world through the eyes of the user every step of the way.