Automatic validation method for multimedia product manuals

Abstract

A Product Document Constraint Specification Language (PDCSL) is provided for a document author to represent various types of documentation guidelines that must be enforced within documents or across different documents. A Document Constraint Analyzer (DCA) takes as input a set of document files together with a document constraint specification file, extracts and examines the contents, attributes, and relationships associated with the document objects, and evaluates the logical expressions specified in the document constraints. If a document constraint is not satisfied, an action can be taken to correct the documents or provide an explanation to the document author.

Description

FIELD OF THE INVENTION

[0002] The present invention relates to multimedia product documentation and, more particularly, to methods and systems for automatic validation of multimedia product manuals.

BACKGROUND OF THE INVENTION

[0003] Product documentation provides important instructions and relevant technical information for properly assembling, operating, and maintaining complex machinery. The quality of product documents is crucial to the success of a product, i.e., the technical information must be up-to-date, accurate, and consistent with a customer's product. Compared to non-technical documentation, the contents and structures of product documents are much more rigid and often comply to various industrial standards. Technical documents also tend to be highly cross-referenced, and often refer users to many different forms of technical data including textual instructions, schematic diagrams, computer-aided design (CAD) drawings, photo images of machine parts, video of inspection procedures, etc. In order to ensure the quality of product documentation, guidelines and standards for technical publication are often used in product development organizations.

[0004] However, documentation guidelines are often written informally and may not be easy to enforce fully. Consequently, the result varies, depending on the degree of self-discipline of the document authors. To support flexible manipulations, multimedia product documents are represented in Standard Generalized Markup Language (SGML). SGML-based product documents can be processed by a SGML parser and other SGML-based tools to extract and examine the contents and attributes of relevant document objects and their relationships. The SGML parser can check the documents against a Document Type Definition (DTD) and report syntax errors. However, the information provided by the SGML parser is based entirely on syntactical structure, which often is too encrypted for the document author to comprehend. On the other hand, documentation guidelines are often based on the semantics of documents, which can only be checked by examining contents and attributes of the relevant document objects. Some documentation guidelines also involve document objects that are not “directly” reedited to one another in the document structure, and thus cannot be easily specified in the DTD.

SUMMARY OF THE INVENTION

[0005] According to various embodiments of the present invention, techniques are provided for automatically validating the contents and structures of multimedia product documents. In the present invention, a Product Document Constraint Specification Language (PDCSL) is provided for the document author to represent various types of documentation guidelines as document constraints that must be enforced within the documents or across different documents. Each document constraint identifies a set of relevant document objects, and specifies a logical expression that is to be evaluated for each combination of the instances of the document objects. A Document Constraint Analyzer (DCA) takes as input a set of document files together with a document constraint specification file, extracts and examines the information associated with the document objects, and evaluates the logical expressions specified in the document constraints. If a logical expression evaluates to true, the corresponding documentation guideline has been followed properly. Otherwise, an action can be specified to correct the documents or provide an explanation to the document author.

BRIEF DESCRIPTION OF THE DRAWINGS

[0006] FIG. 1 illustrates an example of a product manual structure;

[0007] FIG. 2 illustrates an example of a document object;

[0008] FIG. 3 illustrates an example of a document constraint specification;

[0009] FIG. 4 illustrates examples of document logical variables for document objects;

[0010] FIG. 5 illustrates document function symbols for content and attributes;

[0011] FIG. 6 illustrates document predicate symbols for content and attributes;

[0012] FIG. 7 illustrates document pattern matching predicate;

[0013] FIG. 8 illustrates document function symbols for object relationships;

[0014] FIG. 9 illustrates document predicate symbols for object relationships;

[0015] FIG. 10 illustrates document logical operators;

[0016] FIG. 11 illustrates document function symbols for files and directories;

[0017] FIG. 12 illustrates document predicate symbols for files and directories;

[0018] FIG. 13 illustrates an example of validating figure references;

[0019] FIG. 14 illustrates an example of validating an individual object;

[0020] FIG. 15 illustrates an example of validating figure references and figures;

[0021] FIG. 16 illustrates an example of validating figure reference and figure counts;

[0022] FIG. 17 illustrates an example of validating list of figure references and figures;

[0023] FIG. 18 illustrates an example of validating document structure;

[0024] FIG. 19 illustrates an example of validating document references and documents;

[0025] FIG. 20 illustrates an example of a hyperlinked structure;

[0026] FIG. 21 illustrates an example of validating a link object;

[0027] FIG. 22 illustrates an example of validating figure reference links;

[0028] FIG. 23 illustrates an example of validating document reference links; and

[0029] FIG. 24 illustrates an example of validating external media links.

DESCRIPTION OF PREFERRED EMBODIMENTS

[0030] A multimedia product manual includes a set of related product documents, organized in a structured manner to facilitate browsing. A product manual can be as simple as a collection of schematic diagrams and CAD drawings to support manufacturing tasks at the early stages of a product, or as complex as a complete manual set with product documents in various media, including textual documents, schematic diagrams, CAD drawings, photo images of machine parts, and video clips of service procedures, etc., to support operation and maintenance of the product. A multimedia product manual can be organized as a structure of product information for customers or can be organized as a reference to on-line, up-to-date technical information.

[0031] In general, a multimedia product manual is a hierarchical structure of document objects. An example is shown in FIG. 1. Some document objects are actually physical document files, referred to as product documents. It depends on the characteristics of the authoring tools and the document databases that are used to create and maintain the documents. A product manual can be divided into product documents in many ways. In general, a product document is a unit of product information that can be easily manipulated by the authoring tools and authors.

[0032] Product documents are component documents that are classified and assigned with identifiers and properties, and are stored in a document database. A component document may be related to other component documents and media files in the document database. Media files are also managed in the same way as component documents. Component documents and component media can be stored separately as files in file directories or stored directly as blobs in database tables, or objects in archives in a document management system.

[0033] In the present invention, component documents may be represented in Standard Generalized Markup Language (SGML). SGML is a meta-language for defining document structures, referred to as Document Type Definition. An SGML document structure is an instance of its associated DTD.

[0034] Conceptually speaking, the structure of an SGML document is an upside-down tree that is composed of SGML elements (or more generally, document objects). An SGML element is thus either a leaf object whose content is the actual text (or any data code), or an interior object whose content is an SGML sub-structure, in addition to any possible text (or code). An SGML element is also associated with a list of attributes, e.g., id., type, name, that provides additional information to characterize the element. An SGML document structure can also be divided into SGML files in many ways to facilitate editing and maintenance.

[0035] Since SGML is a standard, SGML parsers and SGML-based tools are available in public domain and from vendors for processing and extracting information from SGML documents. The fundamental information that is required in order to check SGML documents are attributes, content, and context of the document objects, as shown in FIG. 2. The context of an object refers to the relationships between the object and all other objects in a document structure. Once the information of individual document objects can be identified and extracted, document objects can be checked individually, or multiple document objects can be checked together for their relationships.

[0036] In the present invention, a Product Document Constraint Specification Language (PDCSL) is provided for document authors to represent documentation guidelines. Each documentation guideline is represented as a document constraint, which is a logical expression (or logical statement) that involves document objects in some SGML documents.

[0037] A logical expression is evaluated and expected to yield true to indicate that the corresponding documentation guideline has been followed properly. However, in general, the exact document objects and the number of them that are involved in a logical expression cannot be determined beforehand. It is thus necessary to extend logical expressions to range-based predicate calculus such that quantifiers may be used to introduce variables and their domains. There are two kinds of quantifiers: universal and existential. Each quantifier defines a single variable and its domain to be used the logical expression that follows. To make parsing and evaluation simpler, a logical expression involving quantifiers are transformed into prenex normal form, i.e., all quantifiers appear first before a logical expression. If a list of quantifiers is specified, the logical expression is evaluated once for each combination of the values of all variables. If no quantifiers are specified, the logical expression is evaluated once only.

[0038] A document constraint specification file comprises a list of document constraint specifications. Each document constraint specification represents a documentation guideline, and it includes four sections: target object declaration with ranges, intermediate object declaration with ranges, counting object declaration with ranges, and if-otherwise document logical expression, as shown in FIG. 3.

[0039] Document logical variables are declared in the first three sections. The target-object-declaration-within-ranges section declares a set of target object variables and their ranges in some SGML documents of which all instances are to be checked in the logical expression that follows. The intermediate-object-declaration-with-ranges section declares a set of intermediate object variables of which at least one instance must also exist within document ranges, and they are often involved in the logical expression. The counting-object-declaration-with-ranges section declares a set of counting objects within ranges to denote the number of different values in the ranges for which some predicates inside logical expressions are true. The if-otherwise-document-logical-expression section includes an antecedent, a consequent, and an action. That is, if the antecedent is evaluated to true, the consequent is expected to be evaluated to true as well; otherwise, an action that follows is to be taken.

[0040] To make the specifications more compact, several constraints that share the same set of document logical variables can be combined. Thus, the logical expression section may contain more than one logical expression, and they are evaluated independently in turn. In addition, it is also possible to encode procedures in the action section to automatically correct the involved documents so that the corresponding documentation guideline is followed properly.

[0041] Target object declarations are used to enumerate “all instances” of a set of target objects that exist in the domain range of some SGML documents. Typically, target objects are document objects (i.e., SGML elements) in SGML documents. Some examples are shown in FIG. 4. The intermediate object declarations are used to identify “at least one instance” of a set of “related” objects in the domain range of the same or different SGML documents. The existence of at least one instance of the specified intermediate objects is the first set of requirements of the documentation guideline represented by the constraint specification. The “under” and “above” operators refer to the domain range which is a set of descendent and ancestor objects, respectively, in the document structure. The root object of a document structure is the first object defined in the SGML document file under the working directory. Refer to FIG. 11 for more details. Thus, the “above e” operator includes all objects above the object “e” up to the root object of the document in which the object “e” exists.

[0042] The keyword “ALL” refers to all types of objects available in a document. A counting object is declared to keep track of the counts of one or more than one type of document objects in the documents; it is handled in the same way as document objects, except that its content (i.e., the count) depends on the number of document objects that satisfy some constraint in the documents. Files and directories are also handled in the same way as document objects. Refer to FIG. 11 for more details.

[0043] Logical expressions are used to specify more complicated requirements that must be satisfied among the set of specified target, intermediate and counting objects. The antecedent and the consequent of each logical expression involve the information of the specified objects, including the SGML tag, attributes, and content of the objects, and the relationships of the objects with all other objects in the documents, as shown in FIG. 5. For an object “e”, content(e) refers to the entire content of the object “e” including the contents of all its descendent objects, while proper content(e) refers to only the content of the object “e” itself, excluding the contents of all its descendent objects.

[0044] In addition, target and intermediate objects can also be patterns that occur in the content or attributes of the document objects, or substrings that occur in some patterns. If an attribute has a string value such as CDATA, patterns of the attribute values can also be specified. For a string “p”, prefix(p) and suffix(p) are sets of all prefix and suffix strings, respectively; and matching-substrings(p) is a function of p and refers to a set of matching substrings of p after a pattern matching is performed.

[0045] Document predicates are also used to test the properties and relationships of document objects, which can be used in the logical expressions of document constraints. Document predicate symbols for testing the content and attributes of document objects are listed in FIG. 6.

[0046] Patterns that exist in the attributes and contents of the objects are often extracted and matched against various naming and numbering schemes defined by the documentation guidelines. In the proposed method, patterns are specified in a form of regular expression. That is, each pattern comprises a sequence of pattern terms, and each pattern term can be a subpattern or a subpattern group. A subpattern group is simply a small sequence of subpatterns enclosed in a pair of “(” and “)”, which can be repeated for one or more times. The pattern matching capability is summarized in FIG. 7.

[0047] A subpattern or a subpattern group that is enclosed by a pair of “/” and “/” causes the matching string to be extracted and stored in the matching object, which can be accessed by the matching-substrings (<matching object>) function. Since sequences of patterns such as a list of figure references or document references are used frequently in technical documents, pattern matching may result in extracting a set of substrings from the document objects, which is used as the domain for checking the properties of the matching substrings. The relationships between objects are based on the hierarchical document structure. In technical documents, each object is related to all its ancestor objects (including parent object), all its sibling objects, and all its descendent objects (including all child objects) in some way. In addition, the first and last objects (of a set of objects) often behave slightly differently, so it is also important to be able to identify them individually. The object relationships are summarized in FIG. 8. However, objects that are not related to one another “directly” can be identified through several levels of the parent-child relationship, e.g., parent(parent(parent(Graphic)))=parent(parent(ParaX)) may be true in some DTD.

[0048] Document predicate symbols for the relationships between document objects in the document structure are listed in FIG. 9.

[0049] There are three sets of operators that are supported, as listed in FIG. 10. The precedence rule is the same as in any programming language, and parenthesis can be used to make evaluation order more explicit. For a set of objects and a single object, the general membership function member( ) is used to check if the specified object exists in the given set of objects.

[0050] As mentioned, physical documents such as multimedia data are typically represented as files in a file structure. It is thus necessary to be able to enumerate files and directories in order to check the presence of multimedia data files that are required in SGML documents. A summary of the file and directory operations is shown in FIG. 11. In the present invention, all identifiable entities are objects. Thus, a physical file is referred to as a file object, and a physical directory is referred to as a set of file objects. For a file object f, content(f) refers to the entire content of the file. Since both file and directory are objects, the general membership function member( ) can also be used to check if a file is in a directory.

[0051] $MMDOCDBDIR usually refers to a top-level, global document directory under which all shared and local document directories are stored, which is often fixed for a particular documentation project. In order to access all local documents that are to be checked by the specified document constraints, working-directory( ) refers to a toplevel, local document directory under which one or more subdirectories of documents are stored, while document-directory (<document file>) refers to one of the subdirectories under which the specified document file exists. If there is only one directory of documents that are to be checked, working-directory( ) is the same as document-directory (any document file).

[0052] Document predicate symbols for testing the relationships between files and directories are listed in FIG. 12.

[0053] To ensure the quality of the product documents, there are several aspects of the product documents that need to be validated against the documentation guidelines. Based on the scope of the information, document validation is categorized into content patterns, individual objects, document structures, and document cross references. To produce professional-quality content, guidelines such as naming convention, cross referencing, etc., which usually appear at the beginning of all technical documents, must be followed properly so that there will be no need for additional explanation throughout the documents, and there will be no misinterpretation by the readers. As an example, C101 in FIG. 13 identifies all paragraphs <ParaX> (at all five levels) in all documents <AnyDoc> in the Operation Manual 31.sgm, and enumerates all patterns “p” in the contents of the paragraphs. If a pattern “p” begins with “Figure”, followed by any number of any characters “[.]+”, then at least there is a prefix “p1” of the pattern “p” that is a valid figure reference, e.g., “FIG. 1”, “FIGS. 1,2, and 3”, or “FIGS. 1-3”. Note that [.] refers to any single character.

[0054] In product documents, technical terms are used to precisely identify machine parts, indicate various measurements, describe technical data, etc. Technical terms are often defined by various industry standards, and must be followed exactly. Similar to figure references, it is also possible to again enumerate all patterns “p” in all paragraphs <ParaX>, and if a pattern “p” resembles a KKS number (a numbering scheme used in the power plant industry), it must follow the numbering scheme defined in the KKS standard and any company-specific guidelines. Refer to FIG. 14 for examples of KKS patterns.

[0055] In SGML, domain-specific structures can be incorporated in documents with domain-specific document objects (i.e., domain-specific SGML tags), which makes the technical data more meaningful and useful for various product-related applications, e.g., extracting technical data for training and market presentations, hyperlinking machine part id's to spare parts lists, etc. Typically, all technical terms in the product documents must be marked up as an <Emphasis> object (or other domain-specific tag such as <KKSNumber>), so that they can be presented in a special font (or manipulated in a specific manner). As an example, C201 in FIG. 14 again enumerates all patterns “p” in all paragraphs <ParaX> in all documents <AnyDoc> in the Operation Manual 31.sgm. If a KKS number (e.g., MBA11CQO11) is found, it is expected to be enclosed in <Emphasis> all by itself. Note that content(a) is the content of an entire paragraph including the contents of all the descendent objects in the paragraph “a”, and there may be intermediate SGML tags between <Emphasis> and a KKS number.

[0056] Compared to content patterns and individual objects, it is more difficult to ensure the consistency of all types of cross references in the product documents. For example, all figure references must refer to figures that actually exist in the same documents, all document references must refer to documents that actually exist in the same product manual, etc. As an example, the constraint C202 shown in FIG. 15 identifies all figure references such as “FIG. 1” in all paragraphs <ParaX> in all documents <AnyDoc> in the Operation Manual 31.sgm, and for each figure reference, it checks for a pattern in a figure title such as <Figure><Title>FIG. 1: . . . </Title> . . . </Figure> that matches exactly the figure reference.

[0057] Some documentation guidelines may refer to the counts of specific types or relationships of document objects in the documents. For example, the number of entries in a table of contents must equal the number of documents that exist in the document directory; otherwise, some documents may have been included or excluded by mistake. For validating object relationships, instead of validating individual documents, a simplified version of validation can also be performed by counting the objects that are involved. As an example, C302 in FIG. 16 counts the number of figure references and the number of figures in the same document, and reports any discrepancy. This type of validation may not be as accurate as validating individual object relationships. However, it provides a summarized view of the object relationships.

[0058] However, the pattern matching problem can get complicated. For example, when the target pattern includes a list of subpatterns, and each subpattern indicates a cross reference which has to be checked for consistency. As an example, C303 in FIG. 17 checks for the list of figure references, i.e., it identifies all figure reference lists such as “FIGS. 1, 2, and 3” in all paragraphs <ParaX> in all documents <AnyDoc> in the Operation Manual 31.sgm. For each figure reference list, it extracts a set of subpatterns (e.g., “1”, “2”, “3”) during pattern matching, then checks each figure reference (i.e., “1”, “2”, “3”, . . . ) in the subpatterns for a pattern in the corresponding figure title <Figure><Title>FIG. 1: . . . </Title> . . . </Figure>, <Figure><Title>FIG. 2: . . . </Title> . . . </Figure>, . . . in the same document.

[0059] In technical documents, some document objects are required in a particular type of documents. For example, all system description documents are required to begin with a list of references such as diagrams, drawings, instructions, test records, etc. As an example, C304 in FIG. 18 checks for the presence of the reference list <ReferToList> as the first child object in the body <AnyDocX> of each document <AnyDoc><DocHeader><DocType>System Description</DocType> . . . </DocHeader><AnyDocX> . . . /AnyDocX><DocFooter> . . . </DocFooter></AnyDoc>.

[0060] It is very important in technical documents that if a reference to a document is made, the referenced document must exist, for example, in the same product manual. As an example, C401 in FIG. 19 identifies all references to Operation documents such as “3.1-1056-9420” in all paragraphs <ParaX> in all documents <AnyDoc> in the Operation Manual 31.sgm, and checks for the presence of the exact document number in the footer <DocFooter> . . . <DocNum>3.1-1056-9420</DocNum></DocFooter> of the corresponding document in the Operation Manual 31.sgm.

[0061] Since SGML documents make references to other media files in the file structure, it is also necessary to check the presence of all the required external media files in the designated directories. Since file and directory are also objects, validating a file reference is similar to validating the presence of any document object. For example, it is possible to enumerate all file reference attributes in all graphic objects in all figures, and check for the corresponding media file in the predefined figure directory under the document directory. Refer to FIG. 24 for an example.

[0062] A set of documents forms a static structure to support sequential reading, validation of the static structure ensures the quality of document content. Since document objects can be identified individually and related to one another by names, id's, or other addressing mechanism, other structures may also be superimposed on top of the static structure. In particular, to support flexible cross referencing in technical documents, a hyperlinked structure is usually created manually or automatically on the set of documents. Thus, validation of the hyperlinked structure ensures the quality of document usage. An example of a hyperlinked structure is shown in FIG. 20. A hyperlink relates one source object to one destination object. The destination object may be located in the same or different document, or may even be an external media file. To establish a hyperlink relationship, typically, the Id attribute of the destination object is recorded in an attribute, e.g., Linkend, of the source object.

[0063] Since PDCSL allows the user to enumerate all document objects in all product documents, it is also possible to specify constraints for the hyperlinking relationship between any two document objects in the same or different product manuals. There are several aspects of the hyperlinked structure that need to be validated, e.g., links for individual objects, links for object relationships, and links to external media files.

[0064] As an example, C501 in FIG. 21 simply checks if all KKS numbers have been linked to some document objects, i.e., each KKS number must be enclosed completely in a Link object, and the Linkend attribute must not be empty. Although such a constraint looks trivial, it can be extremely useful in detecting errors in the documents. For example, since all KKS numbers represent important machine parts referenced in the documents, they are to be linked to all relevant documents such as measurement tables, spare parts lists, schematic diagrams, etc. If a KKS number is not linked to any document, it can only mean that a potential inconsistency has occurred between the set of related documents.

[0065] Since it is not always possible to locate all related document objects in close proximity, hyperlinking is a mechanism to connect any spatially apart objects together, and make them more readily accessible to the readers. Validation of cross references increase the usability of the product documents. As an example, C502 in FIG. 22 checks for the presence of a link from all figure references <Link>FIG. 1 </Link> in all paragraphs <ParaX> to their corresponding figure titles <Figure><Title>FIG. 1: . . . </Title></Figure> in the same document <AnyDoc>.

[0066] From this example, it is also apparent that validating hyperlinked structures often also implicitly validates the corresponding static structures. Similarly, it is also possible to check for the presence of the links from all document references to all documents in the same or different product manuals. As an example, C503 in FIG. 23 enumerates all document references <Link>3.1-1056-9420</Link>in all paragraphs <ParaX> in all documents <AnyDoc>, and checks for the document number stored in <DocFooter><DocNum>3.1-1056-420</DocNum></DocFooter> of all documents <Any Doc> in the same product manual.

[0067] Some links also refer to external media files, as an example, C504 in FIG. 24 enumerates all KKS number links <Link>MBA10CQ011</Link> in all paragraphs <ParaX> in all documents <AnyDoc>, and checks for the presence of the attribute Linkend that refers to a corresponding external schematic diagram in a shared directory $MM1DOCDBDIR/schematics. For a complex, large scale product manual that is composed of hundreds and thousands of files, the capability of validating document references and external file references is a powerful mechanism to ensure the completeness of the product manuals during the authoring process.

[0068] Although illustrative embodiments of the present invention have been described herein with reference to the accompanying drawings, it is to be understood that the invention is not limited to those precise embodiments, and that various other changes and modifications may be affected therein by one skilled in the art without departing from the scope or spirit of the invention.

Claims

1. A method for automatic validation of multimedia product manuals, comprising the steps of: inputting a set of documents and a document constraint specification; extracting information from document objects associated with the set of documents; and evaluating logical expressions contained in the document constraint specification to determine whether the extracted information follows documentation guidelines.

2. The method of claim 1, further including the step of outputting an action message, if it is determined that at least some of the extracted information does not follow documentation guidelines.

3. The method of claim 1, wherein the document constraint specification is written in a product document constraint specification language.

4. The method of claim 3, wherein the product document constraint specification language specifies one or more of valid contents, valid attributes, and valid relationships associated with the document objects.

5. The method of claim 1, wherein the set of documents comprises a multimedia product manual.

6. The method of claim 1, wherein the set of documents are represented in Standard Generalized Markup Language (SGML).

7. The method of claim 1, wherein the document constraint specification defines valid object relationships.

8. The method of claim 1, wherein the document constraint specification defines valid figure references.

9. The method of claim 1, wherein the document constraint specification defines valid figure counts.

10. The method of claim 1, wherein the document constraint specification defines valid document structure.

11. The method of claim 1, wherein the document constraint specification defines valid hyperlinked structure.

12. The method of claim 1, wherein the document constraint specification defines valid link objects.

13. The method of claim 1, wherein the document constraint specification defines valid external media links.

14. The method of claim 1, wherein the document constraint specification defines valid content patterns.

15. A system for automatic validation of multimedia product manuals, comprising: an input device for inputting a set of documents and a document constraint specification; an extractor for extracting information from the set of documents; and an evaluator for evaluating one or more logical expression contained in the document constraint specification to determine whether the extracted information follows documentation guidelines.

16. The system of claim 15, further comprising an output device for outputting an action message, if it is determined that at least some of the extracted information does not follow documentation guidelines.

17. The system of claim 15, wherein the document constraint specification is written in a document constraint specification language.

18. The system of claim 17, wherein the document constraint specification language specifies one or more of valid contents, valid attributes, and valid relationships associated with the document objects.

19. The system of claim 15, wherein the set of documents comprises a multimedia product manual.

20. A program storage device readable by a machine, tangibly embodying a program of instructions executable on the machine to perform method steps for automatic validation of multimedia product manuals, comprising the method steps of: inputting a set of documents and a document constraint specification; extracting information from document objects associated with the set of documents; and evaluating logical expressions contained in the document constraint specification to determine whether the extracted information follows documentation guidelines.