Documentation

Last updated

Documentation is a set of documents provided on paper, or online, or on digital or analog media, such as audio tape or CDs. Examples are user guides, white papers, on-line help, quick-reference guides. Paper or hard-copy documentation has become less common. Documentation is often distributed via websites, software products, and other on-line applications.

Contents

Professionals educated in this field are termed documentalists. This field changed its name to information science in 1968, but some uses of the term documentation still exists and there have been efforts to reintroduce the term documentation as a field of study.

Principles for producing documentation

While associated ISO standards are not easily available publicly, a guide from other sources for this topic may serve the purpose. [1] , [2] ,. [3] David Berger has provided several principles of document writing, regarding the terms used, procedure numbering and even lengths of sentences, etc. [4]

Guidelines

The following is a list of guides dealing with each specific field and type:

Procedures and techniques

The procedures of documentation vary from one sector, or one type, to another. In general, these may involve document drafting, formatting, submitting, reviewing, approving, distributing, reposting and tracking, etc., and are convened by associated SOPs in a regulatory industry. It could also involve creating content from scratch. Documentation should be easy to read and understand. If it's too long and too wordy, it may be misunderstood or ignored. Clear, Short, Familiar words should be used to a maximum of 15 words to a sentence. Only gender hyper neutral word should be used and cultural biases should be avoided. Procedures should be numbered when they are to be performed. [11] , [12] , [13] ,. [14]

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 and managing content (information architecture). Technical writers more commonly collaborate with subject matter experts (SMEs), such as engineers, technical experts, medical professionals, or other types of clients to define and then create content (documentation) that meets the user's needs. Corporate communications includes other types of written documentation that is required for most companies.

Specializing documentation

Indexing

Documentation in computer science

The following are typical software documentation types

The following are typical hardware and service documentation types

Documentation include such as feasibility report, technical documentation, operational documentation, log book, etc.

Tools for documenting software

There are many types of software and applications used to create documentation.

SOFTWARE DOCUMENTATION FOLDER (SDF)

A common type of software document written by software engineers 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, MS 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 work-arounds. 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 FOR NETWORK INVENTORY AND CONFIGURATION (CMDB)

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

Documentation in criminal justice

"Documentation" is the preferred term for the process of populating criminal databases. Examples include the National Counter-terrorism Center's Terrorist Identities Datamart Environment ("TIDE"), sex offender registries, and gang databases. [16]

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" [17]

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. [17]

Pedagogical documentation, in terms of the teacher documentation, is the "teacher's story of the movement in children's understanding". [17] 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" [18]

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" [17] )
  8. The Classroom as Documentation (reflections and documentation of the physical environment of a classroom). [17]

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

Notes

    Related Research Articles

    Acceptance testing

    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.

    The Portable Document Format (PDF) is a file format developed by Adobe in the 1990s to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. Based on the PostScript language, each PDF file encapsulates a complete description of a fixed-layout flat document, including the text, fonts, vector graphics, raster images and other information needed to display it. PDF was standardized as ISO 32000 in 2008, and no longer requires any royalties for its implementation.

    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.

    SQL is a domain-specific language used in programming and designed for managing data held in a relational database management system (RDBMS), or for stream processing in a relational data stream management system (RDSMS). It is particularly useful in handling structured data, i.e. data incorporating relations among entities and variables.

    Configuration management 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 a system used to receive, track, manage and store documents and reduce paper. Most are capable of keeping a record of the various versions created and modified by different users. In the case of the management of digital documents such systems are based on computer programs. 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.

    A technical writer is a professional information communicator whose task is to transfer information (knowledge) 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.

    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 use of a computer by a person with a disability or impairment. Computer accessibility often has direct positive effects on people with disabilities.

    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.

    Change control within quality management systems (QMS) and information technology (IT) systems 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.

    Technical writing is writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, medical, consumer electronics, biotechnology, and forestry. Technical writing encompasses the largest sub-field in technical communication.

    Technical communication is a means to convey scientific, engineering, or other technical information. Individuals in a variety of contexts and with varied professional credentials engage in technical communication. Some individuals are designated as technical communicators or technical writers. These individuals use a set of methods to research, document, and present technical processes or products. Technical communicators may put the information they capture into paper documents, web pages, computer-based training, digitally stored text, audio, video, and other media. The Society for Technical Communication defines the field as any form of communication that focuses on technical or specialized topics, communicates specifically by using technology or provides instructions on how to do something. More succinctly, the Institute of Scientific and Technical Communicators defines technical communication as factual communication, usually about products and services. The European Association for Technical Communication briefly defines technical communication as "the process of defining, creating and delivering information products for the safe, efficient and effective use of products ".

    In software engineering, a test case is a specification of the inputs, execution conditions, testing procedure, and expected results that define a single test to be executed to achieve a particular software testing objective, such as to exercise a particular program path or to verify compliance with a specific requirement. Test cases underlie testing that is methodical rather than haphazard. A battery of test cases can be built to produce the desired coverage of the software being tested. Formally defined test cases allow the same tests to be run repeatedly against successive versions of the software, allowing for effective and consistent regression testing.

    MIL-STD-498 (Military-Standard-498) was a United States military standard whose purpose was to "establish uniform requirements for software development and documentation." It was released Nov. 8, 1994, and replaced DOD-STD-2167A, DOD-STD-7935A, and DOD-STD-1703. It was meant as an interim standard, to be in effect for about two years until a commercial standard was developed.

    Information assurance (IA) is the practice of assuring information and managing risks related to the use, processing, storage, and transmission of information or data and the systems and processes used for those purposes. Information assurance includes protection of the integrity, availability, authenticity, non-repudiation and confidentiality of user data. It uses physical, technical, and administrative controls to accomplish these tasks. While focused predominantly on information in digital form, the full range of IA encompasses not only digital, but also analog or physical form. These protections apply to data in transit, both physical and electronic forms, as well as data at rest in various types of physical and electronic storage facilities. IA is best thought of as a superset of information security, and as the business outcome of information risk management.

    PDF/UA is the informal name for ISO 14289, the International Standard for accessible PDF technology. A technical specification intended for developers implementing PDF writing and processing software, PDF/UA provides definitive terms and requirements for accessibility in PDF documents and applications. For those equipped with appropriate software, conformance with PDF/UA ensures accessibility for people with disabilities who use assistive technology such as screen readers, screen magnifiers, joysticks and other technologies to navigate and read electronic content.

    International standards in the ISO/IEC 19770 family of standards for IT asset management (ITAM) address both the processes and technology for managing software assets and related IT assets. Broadly speaking, the standard family belongs to the set of Software Asset Management standards and is integrated with other Management System Standards.

    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.

    Metadata Data about data

    Metadata is "data that provides information about other data". In other words, it is "data about data." Many distinct types of metadata exist, including descriptive metadata, structural metadata, administrative metadata, reference metadata and statistical metadata.

    In engineering, technical documentation refers to any type of documentation that describes handling, functionality and architecture of a technical product or a product under development or use. The intended recipient for product technical documentation is both the (proficient) end user as well as the administrator / service or maintenance technician. In contrast to a mere "cookbook" manual, technical documentation aims at providing enough information for a user to understand inner and outer dependencies of the product at hand.

    References

    1. ↑ N/A (2003). "Guide to Documentation" (PDF). Archived from the original (PDF) on 29 July 2007.
    2. ↑ CGRP. "A Guide to Documentation Styles" (PDF). Retrieved 12 June 2009.
    3. ↑ N/A. "A guide to MLA documentation" (PDF). Archived from the original (PDF) on 2 September 2006. Retrieved 12 June 2009.
    4. ↑ Berger, David. "Procedures and Documentation" (PDF). Archived from the original (PDF) on 27 July 2011. Retrieved 15 June 2009.
    5. ↑ Springhouse (2008). Complete Guide to Documentation. ISBN   9781582555560 . Retrieved 12 June 2009.
    6. ↑ Tampere University of Technology. "Thesis Writing at the Tampere University of Technology" (PDF). Retrieved 12 June 2009.
    7. ↑ Faculty of Veterinary Medicine, University of Prince Edward Island. "A Guide for the Writing of Graduate Theses" (PDF). Archived from the original (PDF) on 5 June 2011. Retrieved 12 June 2009.
    8. ↑ University of Waikato. "Writing and Submitting a Dissertation or Thesis at the University of Waikato" (PDF). Archived from the original (PDF) on 9 December 2008. Retrieved 12 June 2009.
    9. ↑ Journal of Food Science. "Manuscript Submission". Archived from the original on 25 May 2009. Retrieved 12 June 2009.
    10. ↑ Analytical Chemistry. "Information for Authors" . Retrieved 12 June 2009.
    11. ↑ Cropper, Mark; Tony Dibbens (2002). "GAIA-RVS Documentation Procedures" (PDF). Archived from the original (PDF) on 2 November 2005. Retrieved 15 June 2009.
    12. ↑ N/A. "GLNPO's Quality System Documentation Review Procedures and Tracking" (PDF). Archived from the original (PDF) on 4 December 2008. Retrieved 15 June 2009.
    13. ↑ UK Data Archive (2009). "Data Services Process Guides: Documentation Processing Procedures" (PDF). Archived from the original (PDF) on 13 June 2010. Retrieved 15 June 2009.
    14. ↑ UK Data Archive. "Data Services Process Guides: Documentation Processing Techniques" (PDF). Retrieved 15 June 2009.[ dead link ]
    15. ↑ "XIA Configuration Network Documentation Tool" . Retrieved 8 August 2017.
    16. ↑ 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.
    17. 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.
    18. ↑ "Documentation: Transforming our Perspectives | Project Zero". www.pz.harvard.edu. Retrieved 26 October 2018.
    19. ↑ "ECRP. Vol 13 No 2". ecrp.uiuc.edu. 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.