Information Architecture -- Bottom Up!

By Greg Campbell

Mark Baker's presentation in March, Every Page is Page One, introduced the concept of bottom-up information architecture and provided useful design strategies for bringing tech comm to the web.  But one presentation was not enough, so we had him back again on November 26! Baker provided a more detailed analysis on the issues that plague top-down hierarchical structures, and how the user experience of search & hyperlinking should shape the organization of web-based information.

It is no secret that we use the search function and links to find information on the Internet. The search function is the most popular channel we use to reach content we desire and it is exactly what Baker’s topic-based approach builds upon. Understanding that people use the search function is his logical first step in shaping how technical communication is experienced on the web.

To show that current methods could be better, Baker used old and new encyclopaedias to illustrate the value of topic-based organization.

The title of the image to the right is translated as “figurative system of human knowledge" and is commonly known as the tree of Diderot and d’Alembert. It is suppose to represent the structure of knowledge itself. To find information in here is to follow a sequential order through a family tree of information.

The tree of Diderot and d’Alembert is an example of hierarchical structures and illustrates the top-down approach to information architecture. The common denominator of the top-down approach is the linear sequencing of information.

When a Top-down organization is ported to the web, Baker says to reorganize it with a bottom-up structure. If one does not reorganize the hierarchical structure, users will need to read prerequisite information to understand the information that brought them to the page in the first place. There cannot be context if your document has 210 pages and Google drops the user in at page 78. The user will need to start reading previous pages to situate the info on page 78. Becoming aware that top-down hierarchical structures on the web is not compatible with the way we use the web, is one of the takeaways of Baker’s presentation.

To bring technical information to the web, Baker advocates a reorganization of the information into stand-alone topics. He used a typical Wikipedia page. When users look for technical information, they find it embedded in proper context without having to read previous pages. With the bottom up architecture, the context is always there because every page is the first page. At least with a bottom up architecture, the user will always land on a page that provides context and links to get you to the information you want.

The comparison between encyclopaedias organized by hierarchies and encyclopaedias organized like Wikipedia shows the value of bottom up architecture for the web. The information does not stop here - there is more to come on this topic. Baker has another presentation in the New Year that builds on information architecture bottom-up.

Stayed tuned.

Online File Sharing: A Technical Writer’s Perspective on Hash Checking and Encryption

By Anuradha Satish

As technical communicators, many of us use the Internet to share our work files. SharePoint, Dropbox and Google Docs are among the most common platforms we use to share work.

Recently I came upon a blog article* about Dropbox disrupting the sharing of a document. They alleged copyright infringement based on the DMCA without even looking into the contents of the file. The article described how Dropbox evaluates the legal accuracy or legitimacy of files based on hash algorithms. When a document’s hash code matches one of Dropbox’s blacklisted documents Dropbox can prevent the file from being shared without having to know what it actually contained.

The good news here is that Dropbox is not snooping into our shared files! However, an incident like this makes me wonder how accurate the hash checker is and how safe our documents are when shared online. Let’s take a closer look at what a hash code is and how it operates.

A hash code can be interpreted as a “fingerprint” – it is a unique alpha-numeric code assigned to every document stored in any cloud-shared folder. Here’s a simplified example to show how it works:

• Document A containing 1,2,3,4 could have a hash code assigned as ar59i3nd
• Document B containing 2,1,4,3 could have a hash code assigned as b3nj98he

Each document’s hash code serves as a unique identifier. Storage centers, such as Dropbox, use this hash code to identify the correct document. If the document is altered in any way, the hash code changes. Two versions of the same document will always have two separate hash codes. But if the document matches another document, word-to-word, it will have the same hash code.

Storage centers use hash checkers to validate data. In the case of that article that prompted this blog entry, hash checkers allowed Dropbox to prevent the sharing of a file because its hash code matched that of a black-listed document.

What are the direct implications of this to technical communication?

First, the technical communication industry itself is moving towards online and remote work. Many technical communicators, including writers, illustrators, trainers or editors, have worked or will work for remote clients and share files online. This makes our work easily prone to cyber duplication and plagiarism. It is important to be aware of this potential risk when sharing files.

Second, file encryption is becoming extremely important as more data is transmitted online. Cloud storage service providers can provide a basic level of encryption to ensure data security but, by offering this service, the provider then has the ability to access that content at any time. Instead of leaving it up to the online storage providers, we can take control of the encryption process before sharing documents online. Many free encryption tools offer online encryption services.

Third, be aware and alert once your document is shared online. If you think you have shared potentially confidential information, run a search on popular search engines. If you ever come across web pages that have copied content from your work, or contain similar enough content to make you suspect plagiarism, then you can file a DMCA* complaint with the search engine. The law requires the search engine to prohibit displaying the copyrighted content again. It is a cumbersome manual check but it will ensure that you catch the slightly-different versions of your document which is something that a hash checker will miss.

** Be aware of our laws:

• The Digital Millennium Copyright Act (DMCA) is a United States law against copyright infringement that implements two 1996 treaties of the World Intellectual Property Organization (WIPO). It criminalizes production and dissemination of technology, devices, or services intended to circumvent measures (commonly known as digital rights management or DRM) that control access to copyrighted works. It also criminalizes the act of circumventing an access control, whether or not there is actual infringement of copyright itself. In addition, the DMCA heightens the penalties for copyright infringement on the Internet.
• In Canada, currently it is legal to download any copyrighted file as long as it is for noncommercial use, but it is illegal to distribute the copyrighted files (e.g. by uploading them to a P2P network). Canadian law makers are proposing Bill C-61, an Act to amend the Copyright Act – a controversial Bill that is similar to the American DMCA.

* Original Blog Article
**Source: http://en.wikipedia.org

Making Every Page Page One

By Kourtney Short, STC Member

The ideas that Mark Baker shared in his Every Page is Page One presentation on February 13 are at once practical and exciting. He brings together ideas from usability, e-commerce, computer science, psychology, and his own extensive experience as a technical writer to suggest a better way to structure topics and documents.

When I write, I carefully sequence books and online help so that each topic builds on the last. When I use software, cook, renovate, or do almost any other task you can think of, I google until I can get what I want to done. Finding EPPO topics in my search results would certainly encourage me to look to the official documentation more often.

It’s never easy to convince a documentation team or organization to restructure its documents. Mark Baker’s presentation gave lots of reasons why it’s worth the effort. I liked that he didn’t gloss over the difficulties of bringing about the change on tight deadlines and in resistant organizations. (And reading his book gave me even more ideas.)

I look forward to writing some Every Page is Page One topics of my own.

You can see the slides from a presentation similar to the one that Mark Baker gave on February 13 on Slideshare.


About the author
Mark Baker is a Content Strategist and Structured Writing expert, and author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web.

Linear Versus Agile Documentation Lifecycles & Best Practices

By Anuradha Satish

As a technical documentation specialist, I have created documents for a variety of business purposes – procedure writing, requirements and specifications for system enhancements, training and development, use and test cases, release notes, white papers, and so on.

In my experience, every documentation project needs a customized workflow, depending on time, budget, and team constraints. In general, project workflows can be classified into one of two types: the Linear and Agile models.

Linear Model

Traditional linear workflows tend to include processes that follow what is commonly known as the ADDIE principle:

• (A) Analysis – Preliminary discussion and deciding the project scope
• (D) Design – Preparing a detailed documentation plan
• (D) Development – Devising the template, style guide, and keywords
• (I) Implementation – Producing content
• (E) Evaluation – Review and approval

The following flowchart is an overview of a linear documentation workflow:

(Click to enlarge the image)

While the time-tested ADDIE methodology has many clear advantages, it has one distinct weakness: the potential for last-minute ugly surprises.

For example, if limitations of the documentation plan or template are discovered during the Implementation phase, the content creator is left with little choice but to go back and pretty much start over from scratch. The Review phase only begins after the entire content is produced, which requires the reviewer/approver to allocate a large chunk of time and effort to go through the entire document at one go. If the reviewer is not satisfied with the product, the entire process has to be repeated to identify the problem areas.

Agile Model

The limitations of a linear model can be overcome using an agile approach, where development occurs in phases after periodic review and feedback. It is an iterative process and the document is constantly evolving.

Many product development lifecycles have switched to an agile methodology. Modern software applications are often created using this iterative process where the client is equally responsible for providing effective and timely feedback to ensure that the end result is user-friendly and meets business objectives.

When product documentation follows an agile life cycle, it could result in effective communication that is churned out in a regular and timely manner.

A high-level process workflow in an agile environment would look something like this:

(Click to enlarge the image)

As the flowchart illustrates, more versions of a single document are created as compared to an ADDIE approach. The agile method ensures that new product functionality is documented and updated over time. Assessment and feedback are on-going processes, so it eliminates the need to review all content at once and ensures a thorough check.

However, if content producers jump into the writing stage expecting the best results to come only from review or client feedback, there are bound to be more iterations and document versions, thereby increasing time and cost for the company. With no tangible target to achieve, edits and revisions can simply go on and on, delaying SLAs and project completion dates.

Best Practices – A Hybrid Approach

Neither the ADDIE model nor the agile workflow on their own can be ideal in all situations. Analyzing the business need will drive the most suitable methodology. Consider two crucial questions when deciding on the workflow method:

1. Is the company prepared to invest money, time, effort, and resources on revisions?
2. Can the deadline be stretched?

The nature of the document or product could also point at the best-suited development method.

For example, when developing a new document from scratch, following an agile method allows the product to evolve as required over time. But when the end product is an update to an existing version, the linear method is more suitable as the proof of concept is ready to guide Implementation and Review phases.

Applying one critical stage of an ADDIE approach to any agile environment can make the latter as accurate and flawless as practically possible: Pre-development planning. A comprehensive document plan detailing possible topics, reviewers, approvers and target dates can help speed up the documentation process and result in fewer revisions.

A pre-planned agile workflow can bring out the best of both models as follows:

(Click to enlarge the image)

Getting a Foothold in Canada's Technical Communication Field

By Anuradha Satish

As I write this blog post for the Southwestern Ontario chapter of the STC, I have a feeling of achievement and contentment. From being a new immigrant to Canada who experienced the initial hardships of settling down with two young kids, to getting enrolled in Seneca’s technical communication program, to developing a growing network of professionals – it’s been a terrific roller coaster ride!

Thanks to Rob Cundari, the STC Southwestern Ontario Chapter president and my professor at Seneca, I am using this platform to share thoughts on my adventurous journey so far.
 
I started my career in 2004 in the field of communication — I dabbled in journalism and corporate communication before becoming an Instructional Designer. Having six years of experience writing and editing technical documents and training manuals mostly for North American clients, I presumed my move to Canada would be a step towards my passion – being a technical communicator.

Immigration comes with its share of ups and downs, and if you’re 30, it surely comes with a whole lot more! While I enjoyed the new lifestyle, I missed my work! There were a couple of consultation projects but nothing consistent came along my way. It took two years of frustration, introspection (and a trip back home!) to make me realize that I wanted to do nothing else but write and edit. But with no contacts or mentors, I was at a dead-end, or seemingly so...

The proverbial light at the end of the tunnel came in the form of Seneca College’s technical communication program at York University. There are other universities offering similar programs; I chose Seneca because of the mandatory co-op term, which promised to fill the ‘Canadian-experience’ gap in my resume. Getting through the entrance test, the orientation process and the entire ‘going-back-to-school’ feeling surely excited me, but I was equally nervous – what if I don’t enjoy the program? What if I don’t learn anything new? What if I just don’t like it?

The answers came in the first week of September 2013, when I began my life as a student. The subjects were extremely interesting – Technical Writing, Editing, Programming and Coding, Information Technology, and software tools such as MS Word, Adobe Frame Maker and RoboHelp — I enjoyed every class! 

The professors are experienced professionals who are well-versed with industry practices and share much more than bookish knowledge. They opened doors to the STC – more networking opportunities! And the classroom is full of enthusiastic and eager learners like me – and before I knew it, I was already learning so much from everyone.

The program has sharpened my writing and editing and helped me upgrade my technical skills. For someone who only drafted in MS Word, learning the benefits of Adobe Frame Maker, Adobe RoboHelp, VBA and HTML was a great confidence boost. And it showed during my interview for the co-op placement — I got hired by the first company who interviewed me!

As I write this blog entry, it has been a month into my co-op. I am putting to practice the skills I learned at Seneca and sharing useful tips with my colleagues. The positive feedback I receive is heartening – it makes the entire journey worthwhile!

I would love to hear how and why you got in to the technical communications field yourself, and any advice you have for new writers looking to join our profession. Perhaps you can encourage more people like me who are looking forward to a challenging and successful career ahead.

Thank you!