Jump to navigation. Using a wiki for documentation isn't a new idea. Countless open source projects do. If you're looking for a way to write and publish documentation quickly, a wiki can be a viable alternative to the many technical writing tools out there. That said, the documentation on many wikis isn't always as effective as it could be, and you can use some techniques to help you make the documentation on your wiki more effective and more readable.
You can use these tips whether you're creating new documentation on a wiki or if you're moving existing documentation to one. I've learned one lesson from spending over 20 years in the trenches a technical writer: No one likes reading thick manuals.
It doesn't matter if you start off writing documentation on a wiki or move your documentation to a wiki, those wikis can become online versions of thick manuals. Far too often an entire chapter in a manual becomes a single page on a wiki, and that's a lot of text and images for a reader to wade through using a browser. Remember to move away from the model of the book.
Instead, break your documentation into manageable chunks. Effective documentation on a wiki should be a structured collection of those chunks, and not just a big slab of information that's dropped in front of a reader.
You can do that using the principles of "topic-based writing. For example, the introduction to a chapter is one page, a procedure is another page, and so on. If you have long procedures in your documentation, you can break them into several shorter pages. You might have short pieces of content like a single-paragraph overview or a one- or two-step procedure. Putting content like that on its own page doesn't make sense. In fact, pages like that look out of place.
Instead, keep that content where it is. You'll wind up with a slightly longer wiki page, but that's preferable to having a set of pages that seem like an afterthought. Taking a topic-based approach can result in disjointed documentation in which little, if any, continuity between topics exists, but it doesn't have to be that way.
You can get around the disjointed nature of topic-based documentation with proper navigation. Well-thought-out navigation helps readers to move around topics on a wiki easily and quickly and to find any additional information they might need. Adding links to your wiki pages involves a lot of manual work, but doing so is worthwhile because it makes your reader's experience much smoother. Documentation has to have an aesthetic strategy. It has to be friendly, not just in the way it's written, but in the way it presents itself.
It should be easy to read, look attractive, and look like something you want to engage with. Most documentation that appears on a wiki looks like… well, it looks like it's on a wiki.
There's nothing wrong with that, but readers expect a bit more, and that means making the wiki itself attractive to readers.
Method 2. Determine the business reasons for your documentation. Although the functional reason for documenting software is to help users understand how to use the application, there are other reasons as well, such as assisting in marketing the software, enhancing the company image, and most notably, reducing technical support costs. In no case, however, should software documentation substitute for poor interface design. If an application screen requires reams of documentation to explain it, better to change the screen design to something more intuitive.
Understand the audience you're writing the documentation for. In most cases, software users have little knowledge of computers outside of the applications they use. There are several ways to determine how to address their needs with your documentation. Look at the job titles your prospective users hold. A system administrator is likely expert with a number of software applications, while a data entry clerk is more likely to know only the application he or she currently uses to enter data.
Look at the users themselves. Although job titles generally indicate what people do, there can be considerable variation in how certain titles are used within a given organization. By interviewing prospective users, you can get a feel for whether your impressions of what their job title indicates are accurate or not. Look at existing documentation. Documentation for previous versions of software, as well as functional specifications, provide some indication as to what the user will need to know to use the program.
Keep in mind, however, that end users are not as interested in how the program works as they are in what it can do for them. Identify the tasks needed to do the job, and what tasks need to be done before those tasks can be done.
Determine the appropriate format s for the documentation. Software documentation can be structured in 1 of 2 formats, the reference manual and the user guide.
Sometimes, a combination of formats is the best approach. A reference manual format is devoted to explaining the individual features of a software application button, tab, field, and dialog box and how they work. Many help files are written in this format, particularly context-sensitive help that displays a relevant topic whenever a user clicks the Help button on a particular screen. User guides are often formatted as printed guides or PDFs, although some help files include topics on how to perform particular tasks.
These help topics are usually not context-sensitive, although they may be hyperlinked to from topics that are. User guides often take the form of tutorials, with a summary of the tasks to be performed in the introduction and instructions given in numbered steps. Decide what form s the documentation should take. Software documentation for end users can take 1 or several of many forms: printed manuals, PDF documents, help files, or online help.
Each form is designed to show the user how to use each of the program's functions, whether in the form of a walkthrough or a tutorial; in the case of help files and online help, this may include demonstration videos as well as text and still graphics. Help files and online help should be indexed and keyword-searchable to allow users to quickly find the information they're looking for. Although help file authoring tools can generate indexes automatically, it is often better to create the index manually, using terms users are likely to search for.
Printed or PDF user manuals can be written with a word-processing program like Word or a sophisticated text editor like FrameMaker, depending on their length and complexity. Try Doxygen. You comment your code, run Doxygen, and you have a webpage. Yes No. Not Helpful 4 Helpful I have seen keypresses documented in multiple formats. Is there an actual standard for items or are they all different? There is no universal standard; however, it is a good idea to set a standard for your own documents.
They have different styles, so if you write cross-platform documentation, you may end up using some elements from one guide and some from another. Not Helpful 2 Helpful 2. Include your email address to get a message when this question is answered. The text should be arranged for easy reading, with graphics placed as close to the text that refers to them as possible.
Break the documentation down into sections and topics logically. Each section or topic should address a single issue, be it a single program feature or task.
Related issues can be addressed with "see also" listings or hyperlinks as necessary. Helpful 0 Not Helpful 0. Any of the documentation tools listed above can be supplemented with a screenshot-creating program, such as Snagit, if the documentation requires a number of screenshots. As with other documentation, screenshots should be included to help explain how the software works, not to dazzle the user. Tone is particularly important, especially when writing software documentation for end users.
Address users with the second person "you" instead of third person "users. Helpful 0 Not Helpful 1. Submit a Tip All tip submissions are carefully reviewed before being published. You Might Also Like How to. How to. Co-authors: Updated: January 19,
0コメント