Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Arguing that current approaches to understanding and constructing computer documentation are based on the flawed assumption that documentation works as a closed system, the authors present an alternative way of thinking about the texts that make computer technologies usable for people. Using two historical case studies, the authors describe how a genre ecologies framework provides new insights into the complex ways that people use texts to make sense of computer technologies. The framework is designed to help researchers and documentors account for contingency, decentralization, and stability in the multiple texts the people use while working with computers. The authors conclude by proposing three heuristic tools to support the work of technical communicators engaged in developing documentation today: exploratory questions, genre ecology diagrams, and organic engineering.
Most technical writers want their documentation to be perfect. That's a laudable goal. But you'll never achieve it. So, why not make your work as good as you can, and not stress about it not being perfect
As wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them?
Some writers truly hate Adobe Acrobat and any tool that can do the job better is worth a shot, particularly if it’s open source and easily navigated. Flossmanuals.net introduces FLOSS which does a lot of the single desktop Acrobat Pro’s job - collaboratively and open source.
This chapter is intended to provide a quick introduction to structured markup (SGML and XML). If you're already familiar with SGML or XML, you only need to skim this chapter. To work with DocBook, you need to understand a few basic concepts of structured editing in general, and DocBook, in particular. That's covered here. You also need some concrete experience with the way a DocBook document is structured.
Gets you started with DocBook, an SGML/XML dialect that describes the content of technical articles and other documents. David discusses the benefits of using DocBook, and then describes how to plan and modularize a large document conversion project.
I commented that many tech writers aren't interested in doing more tech writing in their spare time, but might be interested if doing so can help them professionally. In particular, folks coming into the field, either out of school or as career changers, need writing samples for their portfolio to show to prospective employers.
The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?
No one reads the documentation. Maybe that's because the manual as we know it is at the end of its usefulness. A key to making documentation more palatable and useful is to make it more like the information that users are finding on the Web. Focus on specific tasks, not features. Task-based documentation, but to the extreme.
The current trend among technical communicators is a twisted form of minimalism that says the documentation should contain procedural documentation but little or no reference documentation. I believe that this trend is a disservice to our customers and tends to increase technical support costs because customers subjected to this form of documentation have little or no access to the information they need. If it’s not there, they can't find it.
We as technical communicators ought to afford each other the courtesy of using each other’s materials when the need arises. As the writers, we know how valuable it can be, and if we don’t use it when the need arises, we’re contributing to the prevalent concept that “no one reads it anyway.” By doing so, we shoot our own profession in the foot.
A glossary is an alphabetically arranged list of terms, with a definition or an explanation of each term. A term can be a single word or many words. Typically, in a printed document, the glossary is at the end of the document. Usually, in online help, each term in a topic, or the first instance of a term, has a popup that explains the term.
The GNOME Documentation Project (GDP) aims to provide GNOME and GNOME applications with a complete, intuitive, and clear documentation system. At the center of the GDP is Yelp, which presents a unified interface to GNOME-specific documentation as well as other Linux documentation such as man pages and texinfo documents. The GNOME Help System provides a comprehensive view of documentation on a machine by dynamically assembling the documentation of GNOME applications and components which are installed.
In this age of information, advanced technology gives us access to more than ever imagined. Are people easily moving toward gathering information online instead of from paper? This study investigated novice and expert user access of paper versus online documentation.
Aaron and I advocate minimalism in documentation. Our definition of minimalism differs slightly from how some people may define the term, and we take some heat for it. But no matter how you define it, the aim of minimalist doucmentation is always the same. To give user the information they need in the most concise, readable, and accessible way.
Companies are increasingly operating world wide. As a result they often need to produce documentation in several languages to meet market demands. The quality of the source document plays an important part in controlling the cost and release date of the localised documents. This article discusses several issues that need to be considered when producing documents for the multilingual marketplace.
There are numerous tools that you can use to create online documentation. However, each tool has its strengths and weaknesses, and each is more appropriate for some types of information than others. This workshop explores many issues of online documentation tools: Why go beyond Windows Help? Which is better: HTML or Adobe Acrobat? What tools support cross-platform presentation? When should you use Workgroup tools such as Lotus Notes or Folio? When does SGML make sense? How to utilize a!ocument databases? When to use Management tools? Real examples developed using these tools will be given throughout the session. Participants will leave with a clear understanding of the pros and cons of each.
We've been hearing about the paperless office since (at least) the 1990s. Then, people predicted that within 10 years every office would be paperless. That prediction was way off. And going paperless with documentation can be a challenge.
Moving user documentation from paper to online requires long–term planning and hard work. You must rethink how you design documents and determine the best way to present information online. You can take steps to downsize the existing documentation workload. You may even change the way you work with the software development staff. As a result, you will probably produce better documents, start working a lot smarter and save the company a lot of money.
I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent.
Help content gets no respect. For one thing, it is content, and our horse-before-cart industry is only now beginning to seriously tackle content strategy. For another, we assume that our site is so usable, nobody will ever need the help content anyway. Typically, no one is in charge of the help content and no strategy exists to keep it up to date. On most sites, help content is hard to find, poorly written, blames the user, and turns a mildly frustrating experience into a lousy one. It's time to rethink how we approach this part of our site. Done well, help content offers tremendous potential to earn customer loyalty. By learning to plan for and create useful help content, we can turn frustrated users into our company's biggest fans.