Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Writers in our Vancouver office use several procedures to simplify the writing process, improve the final product, and avoid unnecessary work. These procedures include: an online library thatcontainsthe tools, instructions, and documentation we can share; a style guide that gives rules for usage, spelling, formatting, and punctuation; macros, style sheets, and boilerplate text to speed repetitive tasks and improve consistency; and detailedchecklists of the steps in ourmajortasks.
Although videos have been traditionally used for technical training, traditional technical communications take the form of user manuals, help documentation, and instructional guides. Technology has arguably blurred the lines between “traditional” technical communications materials and “traditional” technical training materials. Technical writing has begun to morph with technical training. The once-clear difference between documentation and training now lends itself to the ever-growing trend of super hybrids. Just do a search for “technical writer” or “instructional designer” on any popular job search engine; you’ll find that the title “Technical Writer” today requires us to understand and create job aids, e-learning content, and learning management systems along with all the traditional user manuals, audience analysis, and usability testing.
Summarizes psychological research on why some people learn better from examples than others do, and applies the results to improve software documentation and literacy outreach projects.
Michael Pick’s screencasts on WordPress.tv are, in my opinion, perfect screencasts. They’re the best I’ve seen — and I’m not just saying this because the video quality is crisp and the audio is rich. Pick blends filmography techniques with screencasting. Instead of the typical screencast that focuses almost entirely on the screen, with a disembodied voice narrating at length around a cursor’s boring movement, Pick fills his screencasts with eye candy and motion, moving from visual to visual as he narrates, giving you a conceptual understanding more than a detailed nitty-gritty how-to.
One of my earlier careers was in manufacturing management, and it grounded me in the principles of project planning and management. When I moved into technical communication, I brought my project management disciplines with me, and I embraced the prevailing tools of my new profession. I dutifully produced documentation plans in Microsoft Word and supported them with detailed project plans in Microsoft Project. However, the problem is that—like bad relationships—these artifacts never gave back results that were sufficient to reward the effort I put into creating them.
For many years, employee retirement was considered a normal part of attrition. Today, however, that attrition is becoming a major concern in organizations. In the United States alone, the so-called “baby boomer” generation (those born between 1946 and 1964) has already begun retiring. This concern is one for which policies and procedures (P&P) communication is being called to the rescue.
Overall, I think Flare’s mobile webhelp is a good first attempt at a mobile format, but it needs some refinement and potential readjustment. Despite my reservations about the complexity of responsive design, I would like to see the HTML5 help look better on mobile devices by default. Regardless of the shortcomings I pointed out in Flare’s Mobile Webhelp format, this format has given me a powerful tool for me to add value to mobile projects. I can better pitch our group’s services to mobile teams and show them an output that their app needs. So far it has worked well.
Known to write a script or two to automate repetitive tasks like help builds, she also likes to write posts about XML-based information models like Darwin Information Typing Architecture (DITA). She often experiments with online help technology, enjoys writing blog entries, and wants to find new ways to use communication to help people understand technical solutions to complex problems.
Documentation will almost never be a pre-sales emphasis, that is, something to attract and persuade customers into buying the product, because the mere presence of documentation suggests that the product might be hard to use. However, just because we downplay documentation in the pre-sales scenario, it doesn’t mean that we relegate documentation to something unimportant, only that we sell documentation another group entirely. Instead of selling documentation to the end-user, we sell it to the support group.
This article describes the influence that Extensible Markup Language (XML) will have on the software documentation process and subsequently on the curricula of advanced undergraduate and master's programs in technical communication. XML, an evolving set of standards for storing and displaying information, uses nine components that make up the XML development process. Grouped into content, formatting, and language specifications, these components enhance organizations' ability to manage information more efficiently and accurately. As the XML development process is adopted, the software documentation process will evolve from a self-contained procedure into a more flexible, interactive process in which software documenters must work closely with a wide range of specialists. The changes that XML will have on the software documentation process will likewise have implications for programs in technical communication in the need to address new kinds of job descriptions, skill sets, and career paths of future technical communicators. The article recommends adaptations to existing courses, as well as new elective and required courses.
XML Schema documents are deﬁned using an XML syntax, which means that the idea of generating schema documentation through standard XML technologies is intriguing. We present X2Doc, a framework for generating schema-documentation solely through XSLT. The framework uses SCX, an XML syntax for XML Schema components, as intermediate format and produces XML-based output formats. Using a modular set of XSLT stylesheets, X2Doc is highly conﬁgurable and carefully crafted towards extensibility. This proves especially useful for composite schemas, where additional schema information like Schematron rules are embedded into XML Schemas.
What quicker way can there be to find out if something is teachable than to write up task-oriented documentation? And as things are built or changed, the documentation is updated. I often update the documentation before the code!
Extreme Programming (or XP) is a popular software development process that encourages a return to the days of little or no documentation, Design After First Testing, and Constant Refactoring After Programming. Despite its popularity, not everyone thinks XP is a good idea.
It is acceptable to assess your organization’s content requirements and embark on a strategy of producing indifferent content cheaply (the “meh” strategy). The vast majority of organizations who adopt a laissez-faire attitude, however, have not thought through the implications.
This weekend I had to replace the solenoid in my Frigidaire Gallery refrigerator. The solenoid controls the flow of water into the ice maker, among other things. I’m not a technician, so when I received the new solenoid and looked at the instructions, I was a little hesitant to do what the text said. The text instructions took 30 seconds to read, whereas a YouTube video I found took 9 minutes to watch. But since I was unfamiliar with the process, I preferred the video to make sure I was doing the task right.
Documentation sometimes contains a section titled, 'Frequently asked questions' or 'FAQs'. The TechScribe website used to have a page of FAQs, but better options exist, and therefore, we removed the FAQs.
This paper covers the usability testing of a prototype digital library. The library holds technical manuals for scientific instruments. Findings show test subjects can locate desired documents faster with this digital library than a corresponding paper library. However, the same subjects can locate desired information faster in a paper document than a digital one. Finally, most subjects reported they would prefer to using the online library of technical documents over the library of paper ones.
Doc-To-Help 2000 has a new 'fault tolerance' feature that forgives novice authors their Microsoft Word mistakes, including direct formatting and stretched bookmarks. These problems often cause corrupted cross-references as well as document-to-Help-system conversion problems. Doc-To-Help's automatic diagnostic and repair utilities now find these common errors and correct them automatically.
Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.
Power user. It’s a term that I don’t like. But there definitely are people out there who are working with the software and hardware that we document who want more than just basic information. Getting them that information can be tricky.
There's a lot of great free and Open Source (FOSS) software out there. But one area in which it's lacking is professional-level help authoring tools. In 2005, Linux.com published an article titled "FOSS help authoring tools falter". And not much seems to have changed in the intervening years.
When it comes to truth, my approach is to be candid and honest in formats that live on the web, which I can update on the fly. But when I’m printing hundreds of copies of a guide, which I know will be pinned up on walls, filed in desk drawers, and laminated for long-term reference, I often lie and don’t mention the bugs, hoping that developers will soon fix them and convert my fiction into truth.