Documentation

Last updated

Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance, and use. [1] As a form of knowledge management and knowledge organization, documentation can be provided on paper, online, or on digital or analog media, such as audio tape or CDs. Examples are user guides, white papers, online help, and quick-reference guides. Paper or hard-copy documentation has become less common.[ citation needed ] Documentation is often distributed via websites, software products, and other online applications.

Contents

Documentation as a set of instructional materials shouldn't be confused with documentation science, the study of the recording and retrieval of information.

Principles for producing documentation

While associated International Organization for Standardization (ISO) standards are not easily available publicly, a guide from other sources for this topic may serve the purpose. [2] [3] [4] [5]

Documentation development may involve document drafting, formatting, submitting, reviewing, approving, distributing, reposting and tracking, etc., and are convened by associated standard operating procedure in a regulatory industry. It could also involve creating content from scratch. Documentation should be easy to read and understand. If it is too long and too wordy, it may be misunderstood or ignored. Clear, concise words should be used, and sentences should be limited to a maximum of 15 words. Documentation intended for a general audience should avoid gender-specific terms and cultural biases. In a series of procedures, steps should be clearly numbered. [6] [7] [8] [9]

Producing documentation

Technical writers and corporate communicators are professionals whose field and work is documentation. Ideally, technical writers have a background in both the subject matter and also in writing, managing content, and information architecture. Technical writers more commonly collaborate with subject-matter experts, such as engineers, technical experts, medical professionals, etc. to define and then create documentation to meet the user's needs. Corporate communications includes other types of written documentation, for example:

Documentation in computer science

Types

The following are typical software documentation types:

The following are typical hardware and service documentation types:

Software Documentation Folder (SDF) tool

A common type of software document written in the simulation industry is the SDF. When developing software for a simulator, which can range from embedded avionics devices to 3D terrain databases by way of full motion control systems, the engineer keeps a notebook detailing the development "the build" of the project or module. The document can be a wiki page, Microsoft Word document or other environment. They should contain a requirements section, an interface section to detail the communication interface of the software. Often a notes section is used to detail the proof of concept, and then track errors and enhancements. Finally, a testing section to document how the software was tested. This documents conformance to the client's requirements. The result is a detailed description of how the software is designed, how to build and install the software on the target device, and any known defects and workarounds. This build document enables future developers and maintainers to come up to speed on the software in a timely manner, and also provides a roadmap to modifying code or searching for bugs.

Software tools for network inventory and configuration

These software tools can automatically collect data of your network equipment. The data could be for inventory and for configuration information. The Information Technology Infrastructure Library requests to create such a database as a basis for all information for the IT responsible. It is also the basis for IT documentation. Examples include XIA Configuration. [11]

Documentation in criminal justice

"Documentation" is the preferred term for the process of populating criminal databases. Examples include the National Counterterrorism Center's Terrorist Identities Datamart Environment, sex offender registries, and gang databases. [12]

Documentation in early childhood education

Documentation, as it pertains to the early childhood education field, is "when we notice and value children's ideas, thinking, questions, and theories about the world and then collect traces of their work (drawings, photographs of the children in action, and transcripts of their words) to share with a wider community". [13]

Thus, documentation is a process, used to link the educator's knowledge and learning of the child/children with the families, other collaborators, and even to the children themselves.

Documentation is an integral part of the cycle of inquiry - observing, reflecting, documenting, sharing and responding. [13]

Pedagogical documentation, in terms of the teacher documentation, is the "teacher's story of the movement in children's understanding". [13] According to Stephanie Cox Suarez in "Documentation - Transforming our Perspectives", "teachers are considered researchers, and documentation is a research tool to support knowledge building among children and adults". [14]

Documentation can take many different styles in the classroom. The following exemplifies ways in which documentation can make the research, or learning, visible:

  1. Documentation panels (bulletin-board-like presentation with multiple pictures and descriptions about the project or event).
  2. Daily log (a log kept every day that records the play and learning in the classroom)
  3. Documentation developed by or with the children (when observing children during documentation, the child's lens of the observation is used in the actual documentation)
  4. Individual portfolios (documentation used to track and highlight the development of each child)
  5. Electronic documentation (using apps and devices to share documentation with families and collaborators)
  6. Transcripts or recordings of conversations (using recording in documentation can bring about deeper reflections for both the educator and the child)
  7. Learning stories (a narrative used to "describe learning and help children see themselves as powerful learners" [13] )
  8. The classroom as documentation (reflections and documentation of the physical environment of a classroom). [13]

Documentation is certainly a process in and of itself, and it is also a process within the educator. The following is the development of documentation as it progresses for and in the educator themselves:

See also

    Related Research Articles

    <span class="mw-page-title-main">Acceptance testing</span> Test to determine if the requirements of a specification or contract are met

    In engineering and its various subdisciplines, acceptance testing is a test conducted to determine if the requirements of a specification or contract are met. It may involve chemical tests, physical tests, or performance tests.

    Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in different roles.

    <span class="mw-page-title-main">Standard Generalized Markup Language</span> Markup language

    The Standard Generalized Markup Language is a standard for defining generalized markup languages for documents. ISO 8879 Annex A.1 states that generalized markup is "based on two postulates":

    <span class="mw-page-title-main">Software testing</span> Checking software against a standard

    Software testing is the act of checking whether software satisfies expectations.

    <span class="mw-page-title-main">Configuration management</span> Process for maintaining consistency of a product attributes with its design

    Configuration management (CM) is a systems engineering process for establishing and maintaining consistency of a product's performance, functional, and physical attributes with its requirements, design, and operational information throughout its life. The CM process is widely used by military engineering organizations to manage changes throughout the system lifecycle of complex systems, such as weapon systems, military vehicles, and information systems. Outside the military, the CM process is also used with IT service management as defined by ITIL, and with other domain models in the civil engineering and other industrial engineering segments such as roads, bridges, canals, dams, and buildings.

    A document management system (DMS) is usually a computerized system used to store, share, track and manage files or documents. Some systems include history tracking where a log of the various versions created and modified by different users is recorded. The term has some overlap with the concepts of content management systems. It is often viewed as a component of enterprise content management (ECM) systems and related to digital asset management, document imaging, workflow systems and records management systems.

    An open standard is a standard that is openly accessible and usable by anyone. It is also a common prerequisite that open standards use an open license that provides for extensibility. Typically, anybody can participate in their development due to their inherently open nature. There is no single definition, and interpretations vary with usage. Examples of open standards include the GSM, 4G, and 5G standards that allow most modern mobile phones to work world-wide.

    An open file format is a file format for storing digital data, defined by an openly published specification usually maintained by a standards organization, and which can be used and implemented by anyone. An open file format is licensed with an open license. For example, an open format can be implemented by both proprietary and free and open-source software, using the typical software licenses used by each. In contrast to open file formats, closed file formats are considered trade secrets.

    A technical writer is a professional information communicator whose task is to transfer information between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. Technical writers research and create information through a variety of delivery media. Example types of information include online help, manuals, white papers, design specifications, project plans, and software test plans. With the rise of e-learning, technical writers are increasingly becoming involved with creating online training material.

    <span class="mw-page-title-main">Computer accessibility</span> Ability of a computer system to be used by all people

    Computer accessibility refers to the accessibility of a computer system to all people, regardless of disability type or severity of impairment. The term accessibility is most often used in reference to specialized hardware or software, or a combination of both, designed to enable the use of a computer by a person with a disability or impairment.

    <span class="mw-page-title-main">Flowchart</span> Diagram that represents a workflow or process

    A flowchart is a type of diagram that represents a workflow or process. A flowchart can also be defined as a diagrammatic representation of an algorithm, a step-by-step approach to solving a task.

    ISO/IEC/IEEE 12207Systems and software engineering – Software life cycle processes is an international standard for software lifecycle processes. First introduced in 1995, it aims to be a primary standard that defines all the processes required for developing and maintaining software systems, including the outcomes and/or activities of each process.

    Within quality management systems (QMS) and information technology (IT) systems, change control is a process—either formal or informal—used to ensure that changes to a product or system are introduced in a controlled and coordinated manner. It reduces the possibility that unnecessary changes will be introduced to a system without forethought, introducing faults into the system or undoing changes made by other users of software. The goals of a change control procedure usually include minimal disruption to services, reduction in back-out activities, and cost-effective utilization of resources involved in implementing change. According to the Project Management Institute, change control is a "process whereby modifications to documents, deliverables, or baselines associated with the project are identified, documented, approved, or rejected."

    Technical writing is the writing of technical content, particularly relating to industrial and other applied sciences, with an emphasis on occupational contexts. The range of audiences for technical writing varies widely. By far, the most common form of technical writing is for procedural documentation. Procedural documentation is used in all types of manufacturing to explain user, assembly and installation instructions. In the software industry, procedural documents are also commonly used to describe user operations and installations. In some cases, technical writing may be written for experts or technicians and include specialized information. In most cases, however, technical writers help convey complex scientific or niche subjects to end users in "laymen's" terms. Modern technical writing relies on simple terms and short sentences, rather than detailed explanations with unnecessary information like pronouns, abstract words and/or unfamiliar acronyms. Technical writing is recognized as the largest segment of the technical communication field.

    In the context of software engineering, software quality refers to two related but distinct notions:

    <span class="mw-page-title-main">JSON</span> Open standard file format and data interchange

    JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. It is a commonly used data format with diverse uses in electronic data interchange, including that of web applications with servers.

    An information security audit is an audit of the level of information security in an organization. It is an independent review and examination of system records, activities, and related documents. These audits are intended to improve the level of information security, avoid improper information security designs, and optimize the efficiency of the security safeguards and security processes. Within the broad scope of auditing information security there are multiple types of audits, multiple objectives for different audits, etc. Most commonly the controls being audited can be categorized as technical, physical and administrative. Auditing information security covers topics from auditing the physical security of data centers to auditing the logical security of databases, and highlights key components to look for and different methods for auditing these areas.

    A software audit review, or software audit, is a type of software review in which one or more auditors who are not members of the software development organization conduct "An independent examination of a software product, software process, or set of software processes to assess compliance with specifications, standards, contractual agreements, or other criteria".

    A specification often refers to a set of documented requirements to be satisfied by a material, design, product, or service. A specification is often a type of technical standard.

    Technical documentation is a generic term for the classes of information created to describe the use, functionality or architecture of a product, system or service.

    References

    1. ↑ "Documentation definition by The Linux Information Project". www.linfo.org. Retrieved 9 August 2020.
    2. ↑ "Guide to Documentation" (PDF). somers.k12.ct.us. 2003. Archived from the original (PDF) on 29 July 2007.
    3. ↑ CGRP. "A Guide to Documentation Styles" (PDF). San Francisco State University. Archived from the original (PDF) on 5 January 2011. Retrieved 12 June 2009.
    4. ↑ "A guide to MLA documentation" (PDF). sunyjcc. Archived from the original (PDF) on 2 September 2006. Retrieved 12 June 2009.
    5. ↑ Berger, David. "Procedures and Documentation" (PDF). maintenanceonline. Archived from the original (PDF) on 27 July 2011. Retrieved 15 June 2009.
    6. ↑ Cropper, Mark; Dibbens, Tony (2002). "GAIA-RVS Documentation Procedures" (PDF). mssl.ucl.ac.uk. Archived from the original (PDF) on 2 November 2005. Retrieved 15 June 2009.
    7. ↑ "GLNPO's Quality System Documentation Review Procedures and Tracking" (PDF). U.S. Environmental Protection Agency. Archived from the original (PDF) on 4 December 2008. Retrieved 15 June 2009.
    8. ↑ UK Data Archive (2009). "Data Services Process Guides: Documentation Processing Procedures" (PDF). esds.ac.uk. Archived from the original (PDF) on 13 June 2010. Retrieved 15 June 2009.
    9. ↑ UK Data Archive. "Data Services Process Guides: Documentation Processing Techniques" (PDF). Retrieved 15 June 2009.[ dead link ]
    10. ↑ Springhouse (2008). Complete Guide to Documentation. Lippincott Williams & Wilkins. p. ix. ISBN   9781582555560 . Retrieved 12 June 2009.
    11. ↑ "XIA Configuration Network Documentation Tool". CENTREL Solutions. Retrieved 8 August 2017.
    12. ↑ Rader Brown, Rebecca (2009). "The Gang's All Here: Evaluating the Need for a National Gang Database". Columbia Journal of Law and Social Problems. 42: 293–333.
    13. 1 2 3 4 5 Susan, Stacey (11 May 2015). Pedagogical documentation in early childhood : sharing children's learning and teachers' thinking. St. Paul, Minnesota. ISBN   9781605543925. OCLC   909907917.{{cite book}}: CS1 maint: location missing publisher (link)
    14. ↑ Rivard, Melissa. "Documentation: Transforming our Perspectives | Project Zero". www.pz.harvard.edu. Retrieved 26 October 2018.
    15. ↑ "ECRP. Vol 13 No 2". ecrp.uiuc.edu. Archived from the original on 27 October 2018. Retrieved 26 October 2018.
    This page is based on this Wikipedia article
    Text is available under the CC BY-SA 4.0 license; additional terms may apply.
    Images, videos and audio are available under their respective licenses.