Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
The challenges of documenting entertainment software are in many ways the challenges of all technical communicators. We strive to make the interface intuitive and the documentation interesting and easy-to-read. Although the nature of the world of entertainment may suggest that our task is simple, the breadth of our audience and the depth of our goals makes it more sophisticated than it looks. We must be as imaginative as our users, recognize the emerging dimensions of multimedia, and create with the constraints of low retail costs, small teams, and fast-paced deadlines.
It is commonplace to find information through the Web, but the use of the Web for technical communication is still uncommon. What the competition entries made me realize is that in this networked world, the places where we find information are no longer one or two dimensional. Communication is no longer simply about words on a page (or on a screen). Technical information is now accessed through a multidimensional cyberspace.
The ISO 9000 series of Quality Standards redefines how business will be conducted into the next century. The series is designed to measure the effectiveness of the Quality System in place, thereby ensuring both customer and company needs are always satisfied. The foundation of a robust Quality System is its documentation: problems in this area represent the largest single cause of registration failures. Quality System documentation also forms the basis upon which the 3rd party registrar builds the audit plan for your company.
Describes how technical writers can make their documentation comply with ISO 9001, the latest quality management system from the International Organization for Standardization. The article includes a list of suggested readings.
Documenting networks is playing less with words, and more with diagrams. It also requires an engineering mind, an ability to think out-of-box, and creative mind. Technical writers can rise to a new scale and expand their skill sets if they are able to document networks.
I love reading different community perceptions of both FLOSS Manuals, where we write open docs for open software. I’m also lurking on mailing lists and forums where open source projects are figuring out documentation needs for their users. Forgive me if I ramble a bit, but I’ve been thinking about these concepts lately while discussing them with other writers.
A corporation's or nonprofit's life without written procedures is fraught with dangers and pitfalls that can strike without warning and potentially wreak havoc on the organization's ability to function efficiently—or even to function at all—especially when the lone source of how-to information leaves the organization. The task of creating those procedures from scratch from what often amounts to skeleton information and secondhand sources can be tedious and frustrating but well worth the effort if it helps prevent the organization from being caught off guard in the future. When it comes to workplace procedures, it pays to be prepared.
The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. Thereal challengeistocreateschemasthat arereadablebothdirectlybylookingat their sourcecodeandbydocumentation extraction tools.
With the spread of new technology, technical communicators face interesting new challenges for solving documentation problems. One area of software development that technical communicators are increasingly becoming involved in is that of rule-based expert systems. Because of their complexity, both the systems and their documentation can be difficult to maintain. Technical communicators can solve some of these maintenance problems by flow-charting only the chaining structure of the rule-base design.
While the jobs of Mary Clouse and the rest of the Security and Documentation Unit of the New York State Senate Technology Services department aren't as glamorous as those of the senators themselves, they ensure that the Senate can use its automated systems to conduct its daily business smoothly, efficiently, and securely.
Short deadlines force project teams to quickly design, test, and release the product with little or no design documentation. If these documents are written, they generally are not well-written and are not comprehensive. The fact of the matter is that most project teams do not have enough staff to design the product, let alone write and manage documentation. This situation creates an ideal opportunity for technical writers to assist the project team in more ways than writing a user guide.
This question was raised on a programmer's group recently and I was intrigued. The programmer's point was that with many web applications these days there is no print documentation distributed to end users, and even if it existed, many users won't read it although this makes me wonder who's buying all those how-to books I see in the bookstore. The programmer suggested that applications should be designed without documentation and wondered about the impact that would have on design.
The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it?
I’m working on a little style guide for direct and concise technical writing. One pointer is to avoid the use of should or shouldn’t when what you really mean is do or don’t. Saying something like “shouldn’t” makes it sound optional. In other words, shouldn’t leaves a little room for doubt. Don’t, well, doesn’t.
Your product's unexplained features can turn into costly flaws. This article describes three real-world products with just such "features." It presents ways you can prevent these feature-to-flaw conversions by improving the User Documentation for your products.
There are several main reasons why putting your software manual on-line is necessary. It makes your web-site attractive for search engine crawlers and therefore brings you targeted traffic from Google, Yahoo!, MSN, and other search engines. A good online manual presents your product as serious and credible. Moreover, if a user faces difficulty using your software and asks for technical support, you may easily resolve the issue by referring that user to a certain page of your online help. Simply give the page's URL. With just one click the user will see screenshots and explanations which will help them to resolve the issue.
By partly adopting the process suggested by Daniel Brolund we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.
The document development process is traditionally viewed as a series of steps along a single linear path. Instead, it is useful to view document development as consisting of activities along dual paths: one product-centered and one document-centered. Isolating a product-centered path reveals how much of your time is spent on activities other than writing--for example, learning about the product. It also highlights the ways in which the documentation is dependent on or shaped by the product.
Never assume that describing something in basic, simple, fundamental terms will annoy your audience. Dumbing down is a form of distortion and possibly deception. Simplifying and clarifying are forms of altruistic communication. Find out more about the differences between "dumbing down" and simplifying and clarifying...and how to decide how simple an explanation should be.
I honestly can't remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that's a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. So why do we still maintain a traditional view of how information should be provided?
The STC Code for Communicators requires us 'to communicate technical information truthfully...'. Such truthfulness has two related but distinct aspects, honesty and candor. I have never been asked to falsify technical claims in documentation (honesty), but I have occasionally been asked to withhold true claims about software that, if known to users, would surely affect how they interpret or apply that software (candor). The century ahead will increasingly demand user documentation that is candid as well as honest.
Most technical writers understand online help formats and have worked with at least one over the years. Help file format have evolved from man pages (manual pages in UNIX in the early 1970’s) and HLP files through CHM files and the plethora of HTML-based formats that we have now. E-Book formats are similar in many respects to the common online help formats, but with one crucial difference; they’re designed to work on the small screens of today’s e-readers and tablets.
Lead writing is a process that moves the information development cycle into the product development cycle. Writers and programmers work together from the beginning to produce both code design and supporting information. This process ensures that information developers can actively participate in design, and programmers can contribute to supporting documentation. Both groups gain an appreciation for each other's perspective, expertise, and skills, producing a more customer-oriented product.