Industrial systems, installations and equipment and industrial products — Structuring principles and reference designations — Part Construction works and building services.
Design of graphical symbols for use in the technical documentation of products — Part 1: Basic rules. Design of graphical symbols for use in the technical documentation of products — Part 2: Specification for graphical symbols in a computer sensible form, including graphical symbols for a reference library, and requirements for their interchange.
Design of graphical symbols for use in the technical documentation of products — Part 3: Classification of connect nodes, networks and their encoding. Document management — Part 2: Metadata elements and information reference model. Document management — Part 2: Metadata elements and information reference model — Technical Corrigendum 1. Document management — Part 5: Application of metadata for the construction and facility management sector.
Preparation of instructions for use — Structuring, content and presentation — Part 1: General principles and detailed requirements. Preparation of information for use instructions for use of products — Part 1: Principles and general requirements. Store Standards catalogue ICS 01 ISO Technical product documentation — Part references. ISO Technical product documentation — Data fields in title blocks and document headers. ISO Technical product documentation — Parts lists.
ISO Technical product documentation — Design for manufacturing, assembling, disassembling and end-of-life processing — Part 1: General concepts and requirements. ISO Technical product documentation — Vocabulary — Terms relating to technical drawings, product definition and related documentation. ISO Diagrams for the chemical and petrochemical industry — Part 1: Specification of diagrams. ISO Technical product documentation — Use of main documents. ISO Technical product documentation — Handling of computer-based technical information — Part 1: Security requirements.
ISO Technical product documentation — Handling of computer-based technical information — Part 2: Original documentation.
ISO Technical product documentation — Handling of computer-based technical information — Part 3: Phases in the product design process. ISO Technical product documentation — Handling of computer-based technical information — Part 4: Document management and retrieval systems. ISO Technical product documentation — Handling of computer-based technical information — Part 5: Documentation in the conceptual design stage of the development phase.
Test checklist is a list of tests that should be run at a particular time. It represents what tests are completed and how many have failed. All points in the test checklists should be defined correctly. Try to group test points in the checklists. This approach will help you keep track of them during your work and not lose any. If it helps testers to check the app correctly, you can add comments to your points on the list. This document should describe known problems with the system and their solutions.
It also should represent the dependencies between different parts of the system. Their documentation informs developers how to effectively use and connect to the required APIs. API documentation is a deliverable produced by technical writers as tutorials and guides. This type of documentation should also contain the list of all available APIs with specs for each one. As the name suggests, user documentation is created for product users.
However, their categories may also differ. So, you should structure user documentation according to the different user tasks and different levels of their experience. Generally, user documentation is aimed at two large categories:. The documentation created for end-users should explain in the simplest way possible how the software can help solve their problems.
Such user instructions can be provided in the printed form, online, or offline on a device. Here are the main types of the user documents:. The complete manual includes exhaustive information and instructions on how to install and operate the product. It lists the hardware and software requirements, detailed description of the features and full guidelines on how to get the most out of them, example inputs and outputs, possible tips and tricks, etc.
The troubleshooting guide gives end-users information on how to find and resolve possible issues that might arise when using the product. For a detailed overview, check our article dedicated to user documentation. Some parts of user documentation, such as tutorials and onboarding, in many large customer-based products are replaced with onboarding training.
Nevertheless, there are still complex systems remaining that require documented user guides. User documentation requires technical writers to be more imaginative.
Online end-user documentation may include the following sections:. Written in plain language with visual materials and step-by-step instructions included, user guides can become a powerful marketing tool and increase customer satisfaction and loyalty. Besides, to provide the best service for end-users, you should collect your customer feedback continuously.
The wiki system is one of the more useful practices. It helps to maintain the existing documentation. You can create your wiki pages using a wiki markup language and HTML code. Usually, administration docs cover installation and updates that help a system administrator with product maintenance. Here are standard system administrators documents:. Process documentation covers all activities surrounding product development. The value of keeping process documentation is to make development more organized and well-planned.
This branch of documentation requires some planning and paperwork both before the project starts and during the development. Here are common types of process documentation:. Plans, estimates, and schedules. These documents are usually created before the project starts and can be altered as the product evolves. Reports and metrics. Reports reflect how time and human resources were used during development. They can be generated on a daily, weekly, or monthly basis. Consult our article on agile delivery metrics to learn more about process documents such as velocity chats, sprint burndown charts, and release burndown charts.
Working papers. The majority of process documents are specific to the particular moment or phase of the process. As a result, these documents quickly become outdated and obsolete. But they still should be kept as part of development because they may become useful in implementing similar tasks or maintenance in the future.
Also, process documentation helps to make the whole development more transparent and easier to manage. The main goal of process documentation is to reduce the amount of system documentation. In order to achieve this, write the minimal documentation plan. List the key contacts, release dates, and your expectations with assumptions.
Product roadmaps are used in Agile software development to document vision, strategy, and overall goals of the project. Roadmaps are used as process documents to keep the course of development in sync with initial goals. Depending on the type of product roadmap, it can express high-level objectives, prioritization of tasks, the sprint timeline, or low-level details. A strategic roadmap is a high-level strategic document, that contains overall information on the project.
Strategic roadmaps usually state a vision and long-term goals. In the case of agile product development, a roadmap can be arranged in themes. Themes are multiple tasks that a team must complete and are somehow connected. Grouping the information around the themes makes a roadmap highly flexible and updatable, which is a great fit for sprint-based development.
The best advice concerning strategic roadmapping is to include only important information. Otherwise, you risk turning your roadmap into a clumsy scheme, difficult to both understand and maintain. Source: productplan. A technology roadmap or IT roadmap is a low-level document that describes technical requirements and the means of technology implementation.
IT roadmaps are quite detailed. They contain the information on each deliverable, explaining the reason for such a decision. Source: hutwork. A release plan is used to set strict time limits for releases. A release plan should focus on the actual deadlines without specifying release details.
It is highly recommended to use roadmap specific tools to create your own roadmaps. Online tools like Roadmunk provide various templates for product roadmaps, allow quick editing, and provide easy sharing across all team members. Keep in mind, that a roadmap, depending on its type, can be a product document that states requirements.
It also describes the process and guides your team through development. There are countless collaborative tools for software development teams. Those can help to state requirements, share information, and document features and processes:. As software documentation is easier to be used on the web, it has to be created in a proper format. Markup is used on GitHub and Reddit, and basically everywhere for web-based documentation. So, here are some Markdown editors that can be useful for creating documents for your project:.
Most roadmapping tools provide templates for different roadmaps to let you start working with this document right away. Basically, all the tools offer free trials and paid plans with differences in templates, number of roadmaps, and people you can share them with. The most popular tools for user experience design are prototyping tools that help create sketches, mock-ups, wireframes, and interactive prototypes:. The process of creating API documentation is most often automated.
Programmers or tech writers may write the documentation manually or use API documentation generators:. Professional tech writers often use specialized software for creating high-quality tech documentation. Such tools are called content management systems , or CMSs, and allow for easier building, organizing, and managing various documentation. A CMS can operate different file formats, import and store content, and let multiple users contribute to content development.
Some popular CMSs include:. Many of the tools described in the previous section provide a variety of templates for creating tech documentation. However, if your team is still struggling to find a qualitative template for some type of software documentation, here are more specialized sources to check out. The following sources provide a wide variety of templates related to software development and project management:.
Downloadable templates might be harder to manage and collaborate on, but can still get you started quickly. Here are some sources where you can find a number of roadmap templates:.
Software design documents are sometimes also called product or technical specifications. You can adjust one of these templates to fit your needs:.
Today, as more businesses prefer to migrate to the cloud, there are some well-known trusted providers that offer training and architecture samples to facilitate operating in their environments:.
There are several common practices that can be applied to all the major types of documentation we discussed above. You should find a balance between no documentation and excessive documentation.
Poor documentation causes many errors and reduces efficiency in every phase of software product development. The standard regards documentation services as important elements in the product life cycle and lays down rules for both inclusion and provision. These rules serve to structure cooperation between aquirers and suppliers of information for users.. Both sides are considered in parallel and considered equally. The standard also provides guidance on what needs to be considered from the outset on both sides for successful joint projects.
The annexes to the standard, one with checklists for the ordering party and the other for the supplier, are very helpful. Both appendices contain useful requirements, the consistent consideration of which provides a good basis for a transparent, problem-free flow of information development projects. It is defined what must be clarified and delivered by the ordering party and how the ordering party must behave.
For clients, this standard is a great support, especially if they have no experience with the purchase of documentation services. Thus, the standard declares the necessity for transparently specifying requirements for the user information to be created according to given guidelines. The standard is also a good set of rules for the contracting party. On the one hand, it can refer to what it has to get from the ordering party and, on the other hand, it receives clear specifications as to what it has to achieve and deliver.
For example, the requirements for the contracting party mean that it must be able to present its work to the client in a comprehensible manner at all times. And, for both sides, the important requirement applies that changes to the originally agreed-upon conditions must be communicated openly and at an early stage.
It should be emphasized that the standard is not only applicable if the client and contractor are different companies, but also within a company if the client and contractor are different departments within the same company.
When it comes to regulating cooperation between the contracting parties for information development projects, it is useful in all areas, not just software. Further information. Standard , published in , describes the requirements for the quality assurance of information products and is aimed at reviewers and usability testers. This standard supports those involved in testing and reviewing user information in the context of software and system development.
The standard focuses on the need of users to obtain useful, complete, consistent and correct information about software and systems. There is an important focus on the need to test information products with real users during the development cycle.
The revised version was released in In addition to the change from "documentation" to "information for users" and the extended literature references, the focus of the revision was on evaluation strategies and methods. In addition, there are extended sections on system tests, usability tests, checking the accessibility of user information as well as tests and reviews of translation and localization.
The best innovation is the new appendix with guidelines for user-centered tests and reviews. The guidelines recommend action orientation, consideration of real tasks, attention to error detection and correction and efficient access as test criteria for information products according to the minimalist principles. The approx. The revised version from emphasizes the importance of the content strategy even more. It plays a central role as it affects the entire organization, products and customers.
Compliance, which is also an important topic for managers in the information development process, is also emphasized even more, as it requires them to work intensively with product development. This aspect is particularly interesting for areas with high regulatory requirements, such as medical technology. The Appendices are very helpful, in particular Appendix B with an exemplary project plan for information development and Appendix C with a plan for translation management.
This standard focuses on aspects of information development in an agile project environment. The standard does not deal with a specific agile method, but focuses on aspects that are generally important in an agile environment. These include.
0コメント