Software Engineering for Self-Directed Learners
  • Documentation

    Introduction

    What

    Can explain the two types of developer docs

    Developer-to-developer documentation can be in one of two forms:

    1. Documentation for developer-as-user: Software components are written by developers and reused by other developers, which means there is a need to document how such components are to be used. Such documentation can take several forms:
      • API documentation: APIs expose functionality in small-sized, independent and easy-to-use chunks, each of which can be documented systematically.
      • Tutorial-style instructional documentation: In addition to explaining functions/methods independently, some higher-level explanations of how to use an API can be useful.
    1. Documentation for developer-as-maintainer: There is a need to document how a system or a component is designed, implemented and tested so that other developers can maintain and evolve the code. Writing documentation of this type is harder because of the need to explain complex internal details. However, given that readers of this type of documentation usually have access to the source code itself, only some information need to be included in the documentation, as code (and code comments) can also serve as a complementary source of information.

    Choose correct statements about API documentation.

    • a. They are useful for both developers who use the API and developers who maintain the API implementation.
    • b. There are tools that can generate API documents from code comments.
    • d. API documentation may contain code examples.

    All

    Guidelines

    Guideline: Go Top-down, Not Bottom-up

    What

    Can distinguish between top-down and bottom up documentation

    When writing project documents, a top-down breadth-first explanation is easier to understand than a bottom-up one.

    Why

    Can explain the advantages of top-down documentation

    The main advantage of the top-down approach is that the document is structured like an upside down tree (root at the top) and the reader can travel down a path she is interested in until she reaches the component she is interested to learn in-depth, without having to read the entire document or understand the whole system.

    How

    Can write documentation in a top-down manner

    To explain a system called SystemFoo with two sub-systems, FrontEnd and BackEnd, start by describing the system at the highest level of abstraction, and progressively drill down to lower level details. An outline for such a description is given below.

    [First, explain what the system is, in a black-box fashion (no internal details, only the external view).]

    SystemFoo is a ....

    [Next, explain the high-level architecture of SystemFoo, referring to its major components only.]

    SystemFoo consists of two major components: FrontEnd and BackEnd.

    The job of FrontEnd is to ... while the job of BackEnd is to ...

    And this is how FrontEnd and BackEnd work together ...

    [Now we can drill down to FrontEnd's details.]

    FrontEnd consists of three major components: A, B, C

    A's job is to ...
    B's job is to...
    C's job is to...

    And this is how the three components work together ...

    [At this point, further drill down the internal workings of each component. A reader who is not interested in knowing nitty-gritty details can skip ahead to the section on BackEnd.]

    In-depth description of A

    In-depth description of B

    ...

    [At this point drill down details of the BackEnd.]

    ...

    Guideline: Aim for Comprehensibility

    What

    Can explain the need for comprehensibility in documents

    Technical documents exist to help others understand technical details. Therefore, it is not enough for the documentation to be accurate and comprehensive, it should also be comprehensible too.

    How

    Can write reasonably comprehensible developer documents

    Here are some tips on writing effective documentation.

    • Use plenty of diagrams: It is not enough to explain something in words; complement it with visual illustrations (e.g. a UML diagram).
    • Use plenty of examples: When explaining algorithms, show a running example to illustrate each step of the algorithm, in parallel to worded explanations.
    • Use simple and direct explanations: Convoluted explanations and fancy words will annoy readers. Avoid long sentences.
    • Get rid of statements that do not add value: For example, 'We made sure our system works perfectly' (who didn't?), 'Component X has its own responsibilities' (of course it has!).
    • It is not a good idea to have separate sections for each type of artifact, such as 'use cases', 'sequence diagrams', 'activity diagrams', etc. Such a structure, coupled with the indiscriminate inclusion of diagrams without justifying their need, indicates a failure to understand the purpose of documentation. Include diagrams when they are needed to explain something. If you want to provide additional diagrams for completeness' sake, include them in the appendix as a reference.

    It is recommended for developer documents,

    • a. to have separate sections for each type of diagrams such as class diagrams, sequence diagrams, use case diagrams etc.
    • b. to give a high priority to comprehension too, not stop at comprehensiveness only.

    (a)(b)

    Explanation:

    (a) Use diagrams when they help to understand the text descriptions. Text and diagrams should be used in tandem. Having separate sections for each diagram type is a sign of generating diagrams for the sake of having them.

    (b) Both are important, but lengthy, complete, accurate yet hard to understand documents are not that useful.

    Guideline: Document Minimally, but Sufficiently

    What

    Can explain documentation should be minimal yet sufficient

    Aim for 'just enough' developer documentation.

    • Writing and maintaining developer documents is an overhead. You should try to minimize that overhead.
    • If the readers are developers who will eventually read the code, the documentation should complement the code and should provide only just enough guidance to get started.

    How

    Can write minimal yet sufficient documentation

    Anything that is already clear in the code need not be described in words. Instead, focus on providing higher level information that is not readily visible in the code or comments.

    Refrain from duplicating chunks or text. When describing several similar algorithms/designs/APIs, etc., do not simply duplicate large chunks of text. Instead, describe the similarity in one place and emphasize only the differences in other places. It is very annoying to see pages and pages of similar text without any indication as to how they differ from each other.

    Tools

    JavaDoc

    What

    Can explain JavaDoc

    Javadoc is a tool for generating API documentation in HTML format from doc comments in source. In addition, modern IDEs use JavaDoc comments to generate explanatory tool tips.

    An example method header comment in JavaDoc format (adapted from Oracle's Java documentation)

    /**
     * Returns an Image object that can then be painted on the screen.
     * The url argument must specify an absolute {@link URL}. The name
     * argument is a specifier that is relative to the url argument.
     * <p>
     * This method always returns immediately, whether or not the
     * image exists. When this applet attempts to draw the image on
     * the screen, the data will be loaded. The graphics primitives
     * that draw the image will incrementally paint on the screen.
     *
     * @param url an absolute URL giving the base location of the image
     * @param name the location of the image, relative to the url argument
     * @return the image at the specified URL
     * @see Image
     */
     public Image getImage(URL url, String name) {
            try {
                return getImage(new URL(url, name));
            } catch (MalformedURLException e) {
                return null;
            }
     }
    

    Generated HTML documentation:

    Tooltip generated by Intellij IDE:

    How

    Can write Javadoc comments

    In the absence of more extensive guidelines (e.g., given in a coding standard adopted by your project), you can follow the two examples below in your code.

    A minimal javadoc comment example for methods:

    /**
     * Returns lateral location of the specified position.
     * If the position is unset, NaN is returned.
     *
     * @param x  X coordinate of position.
     * @param y Y coordinate of position.
     * @param zone Zone of position.
     * @return Lateral location.
     * @throws IllegalArgumentException  If zone is <= 0.
     */
    public double computeLocation(double x, double y, int zone)
        throws IllegalArgumentException {
      ...
    }
    

    A minimal javadoc comment example for classes:

    package ...
    
    import ...
    
    /**
     * Represents a location in a 2D space. A <code>Point</code> object corresponds to
     * a coordinate represented by two integers e.g., <code>3,6</code>
     */
    public class Point{
        //...
    }
    

    Markdown

    What

    Can explain Markdown

    Markdown is a lightweight markup language with plain text formatting syntax.

    How

    Can write documents in Markdown format

    AsciiDoc

    What

    Can explain AsciiDoc

    AsciiDoc is similar to Markdown but has more powerful (but also more complex) syntax.