Season of Docs 2019: My Foray into Technical Writing

By Audrey Tavares

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?

Me: …. 

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 Tavares

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.

Why XML?

By Sowmya Sannaiah

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.

XML editor

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.
  • Ease of 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 Sannaiah

Sowmya is a Technical Communicator with experience in IT documentation.

LinkedIn: https://www.linkedin.com/in/sowmya-sannaiah/

Blog: https://sowmyasannaiah.wordpress.com/


STC Toronto Members Won 2020 Distinguished Chapter Service Award

Congratulations to our very own Vanitha Krishnamurthy and Mona Albano for winning this year’s STC Distinguished Chapter Service Award!

The STC Community Affairs Committee gives out this award every year to honor the dedication and hardworks of STC’s community leaders. It is the highest recognition that a STC member can receive.

Mona Albano is currently serving as the Community Director
of the STC Toronto Chapter
Vanitha Krishnamurthy is currently serving as the Treasurer of the STC Toronto Chapter

STC Toronto AGM 2020

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

Communication ManagerNatalya Lohnes
Communications CoordinatorKahkashan Kazmi
Membership ManagerTika Thapa
Program ManagerPhoebe Yu
Education ManagerTania Samsonova
Publicity ManagerVacant
WebmasterEgnis Hoxha
Blog ManagerPeihong Zhu
Content WriterCraig Dodman
Site ManagerManali Pandit
Job Bank MangerAnant Seshardri
Job Bank CoordinatorsKahkashan Kazmi, Michael Fowler

The 2020-2021 executive council

PresidentJoyce Lam
Vice PresidentShonna Eden
TreasurerVanitha Krishnamurthy
Community DirectorMona Albano

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

Awards

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.

Keynote speech

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.

If you want to know more about Kathrine Barber’s work, please visit her blog: https://katherinebarber.blogspot.com/.

Press Enter to Continue

Book Review by Jane Aronovitch

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!

Designing for Disruptive Innovation with Eliane Tozman

Tuesday, April 9 2019, 6 p.m.

The Wallace Gastropub

An Image of Eliane Tozman, Head of Design for IBM Canada Innovation
Eliane Tozman, Head of Design for IBM Canada Innovation

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.

Preparing your Content for Intelligent Machines with Jo Lam

Tuesday, May 14 2019, 6:30-8:30 p.m.

North York Civic Center

Jo Lam

There’s a lot of talk about Content 4.0 and microcontent, but what can technical communicators do about it?

Intelligent agents and AI-powered cognitive content solutions perform best with machine-ready content—intelligent content designed to be read by humans and processed by computers. To deliver the right answer to prospects and customers who have questions, you’ll need to optimize your content production approaches and begin crafting content with the precision humans appreciate, and machines require. Welcome to Intelligent Microcontent.

Join us to talk about our next steps in future-proofing our content.

  • STC Toronto Chapter Members: $5 (taxes included)
  • STC Members (no chapter): $15 (taxes included)
  • Non-STC Members: $25 (taxes included)
  • TechComm Students: Free (please register)

Click here for more detail and to register.

New and Unique STC Roundtable Resources (Limited Time!)

For a limited time, STC is providing those who register now with a free monthly subscription to Roundtable. Each month, Roundtable members receive: over $400 worth of fresh, high-quality content; an engaged community; access to top experts in the field and timely, accurate and targeted resources.

An example month may include: a formal webinar led by the monthly curator or a selected expert; tools for implementing the information learned; a live Q&A on the monthly topic with selected experts moderated by the monthly curator; community connections, resources and more. This is a very cool opportunity for professional development, and a high value for STC members: register for free while you can.

Win a free STC Summit Registration (Limited Time!)

SmartDocs is a complete content management system designed for technical writers which allows your team to work in Word while benefiting from centralized, reusable content. They are raffling off a free STC 2019 Technical Communication Summit Registration (a value of around $2000 Canadian dollars, depending on your membership level). How do you enter? Register for and attend a free SmartDocs demonstration webinar this Wednesday, March 6 from 12-1 p.m. A free webinar and a chance to get into the 2019 STC Summit for free? Not too shabby.

STC’s 2019 Technical Communication Summit

The 2019 STC Summit is in Denver this year, May 5-8.

View the full schedule at https://summit.stc.org/schedule/. There are 80+ sessions and 12 workshops, plus:

  • Opening Keynote by Peter Morville, Information Architecture Expert and co-author of the O’Reilly “Polar Bear” books. Click here for details.
  • Honors Event speaker Gabby Pascuzzi from Survivor. Visit https://summit.stc.org/honors-event-speaker/ for details.
  • Closing General Session speakers Karen Schriver, Saul Carliner, and Ginny Redish. Click here for session details.
  • Certified Professional Technical Communicator (CPTC) Exam Prep Training.
  • An Expo Hall where you can meet with vendors and visit the Tech Comm Library, and
  • fun social events Monday and Tuesday evening, and Wednesday afternoon after the Closing General Session!

Don’t miss this opportunity build your skills and network in a fun and professional environment!