Usage and usefulness of technical software documentation: An industrial case study

ContextSoftware documentation is an integral part of any software development process. However, software practitioners are often concerned about the value, degree of usage and usefulness of documentation during development and maintenance.ObjectiveMotivated by the needs of NovAtel Inc. (NovAtel), a world-leading company developing software systems in support of global navigation satellite systems, and based on the results of a former systematic mapping study, we aimed at better understanding of the usage and the usefulness of various technical documents during software development and maintenance.MethodWe utilized the results of a former systematic mapping study and performed an industrial case study at NovAtel. From the joint definition of the analysis goals, the research method incorporates qualitative and quantitative analysis of 55 documents (design, test and process related) and 1630 of their revisions. In addition, we conducted a survey on the usage and usefulness of documents. A total of 25 staff members from the industrial partner, all having a medium to high level of experience, participated in the survey.ResultsIn the context of the case study, a number of findings were derived. They include that (1) technical documentation was consulted least frequently for maintenance purpose and most frequently as an information source for development, (2) source code was considered most frequently as the preferred information source during software maintenance, (3) there is no significant difference between the usage of various documentation types during both development and maintenance, and (4) initial hypotheses stating that up-to-date information, accuracy and preciseness have the highest impact on usefulness of technical documentation.ConclusionsIt is concluded that the usage of documentation differs for various purposes and it depends on the type of the information needs as well as the tasks to be completed (e.g., development and maintenance). The results have been confirmed to be helpful for the company under study, and the firm is currently implementing some of the recommendations given.     

一种Web应用系统开发平台的研究与设计

为了提高Web应用系统的质量和开发效率,研究并分析了其通用模块开发效率问题,提出了一个Web应用系统开发平台.平台融合了快速原型法和模块化设计思想并改进了Web应用系统开发文档的处理流程,提供文档管理、模块定制、动态编译、版本控制等功能.研究表明该平台将有效地缩短Web应用系统开发中的通用模块开发周期,具有Web应用系统开发生命周期管理、粗粒度控制、模块化开发和快速生成系统原型等优点.     

Using the Unified Modeling Language to develop soil water-balance and irrigation-scheduling models

Many water-balance and irrigation-scheduling models have been developed as research and/or management tools. These models continue to be modified or re-used by other research groups. A method for developing and documenting these models, using the Unified Modeling Language (UML) is presented. This method simplifies documentation of model requirements, assumptions and calculations and provides a template for implementing the model in programming languages. Using the template can simplify the processes of code re-use and model modification.     

基于MSC的TTCN-3测试例生成研究

提出了从消息序列图(MSC)生成TTCN-3测试例的方法.测试者可以先针对被测系统(SUT)中感兴趣的部分利用MSC描述出具体的测试场景,再从MSC映射成TTCN-3测试例.将MSC映射成TTCN.3的方法主要包括对MSC文档、基本MSC和高级MSC这3部分的映射.     

Documenting information systems for management: A key to maintaining user satisfaction

Executives responsible for the information system function need to be concerned about developing a base of satisfied users and maintaining continuing user satisfaction after implementation. This article focuses on user satisfaction among on-going user manager, explores the role of good user documentation, and examines the results of a survey of 144 user managers from 55 firms. The results indicate that good user documentation appears to be an important factor in insuring user understanding and continuing user satisfaction. Thus firms considering alternative ways of keeping users satisfied (i.e., personal computer applications, end user computing, or information centers) might well examine their user documentation practices before exploring other alternatives.     

The case for perspicuous programming

Traditional approaches to coding interactive programs, even literate programming, suffer from the problem of focusing on what the computer will do, not what the user wants it to do. The algorithmic code is primary and any documentation secondary, especially user documentation. Help facilities appear to be added as an almost independent exercise. We can solve this problem by focusing on the user documentation and regarding the algorithmic code as a mere adjunct. The production of an interactive program should start with the user documentation, with the majority of effort spent on developing and refining that documentation and its structure. Developers should add algorithmic code for any program module only after its documentation is complete and all parties have tested and agreed to it. This perspicuous programming approach seeks to produce programs for the user that are as unenigmatic as possible. With a touch of blithely false etymology, we could call this igmatic programming instead. Take your pick.     

How software engineers use documentation: the state of the practice

Software engineering is a human task, and as such we must study what software engineers do and think. Understanding the normative practice of software engineering is the first step toward developing realistic solutions to better facilitate the engineering process. We conducted three studies using several data-gathering approaches to elucidate the patterns by which software engineers (SEs) use and update documentation. Our objective is to more accurately comprehend and model documentation use, usefulness, and maintenance, thus enabling better decision making and tool design by developers and project managers. Our results confirm the widely held belief that SEs typically do not update documentation as timely or completely as software process personnel and managers advocate. However, the results also reveal that out-of-date software documentation remains useful in many circumstances.     

Inclusion of Textual Documentation in the Analysis of Multidimensional Data Sets: Application to Gene Expression Data

Recently, biology has been confronted with large multidimensional gene expression data sets where the expression of thousands of genes is measured over dozens of conditions. The patterns in gene expression are frequently explained retrospectively by underlying biological principles. Here we present a method that uses text analysis to help find meaningful gene expression patterns that correlate with the underlying biology described in scientific literature. The main challenge is that the literature about an individual gene is not homogenous and may addresses many unrelated aspects of the gene. In the first part of the paper we present and evaluate the neighbor divergence per gene (NDPG) method that assigns a score to a given subgroup of genes indicating the likelihood that the genes share a biological property or function. To do this, it uses only a reference index that connects genes to documents, and a corpus including those documents. In the second part of the paper we present an approach, optimizing separating projections (OSP), to search for linear projections in gene expression data that separate functionally related groups of genes from the rest of the genes; the objective function in our search is the NDPG score of the positively projected genes. A successful search, therefore, should identify patterns in gene expression data that correlate with meaningful biology. We apply OSP to a published gene expression data set; it discovers many biologically relevant projections. Since the method requires only numerical measurements (in this case expression) about entities (genes) with textual documentation (literature), we conjecture that this method could be transferred easily to other domains. The method should be able to identify relevant patterns even if the documentation for each entity pertains to many disparate subjects that are unrelated to each other.     

Systematic literature review of the objectives,techniques, kinds,and architectures of models at runtime

In the context of software development, models provide an abstract representation of a software system or a part of it. In the software development process, they are primarily used for documentation and communication purposes in analysis, design, and implementation activities. Model-Driven Engineering (MDE) further increases the importance of models, as in MDE models are not only used for documentation and communication, but as central artefacts of the software development process. Various recent research approaches take the idea of using models as central artefacts one step further by using models at runtime to cope with dynamic aspects of ever-changing software and its environment. In this article, we analyze the usage of models at runtime in the existing research literature using the Systematic Literature Review (SLR) research method. The main goals of our SLR are building a common classification and surveying the existing approaches in terms of objectives, techniques, architectures, and kinds of models used in these approaches. The contribution of this article is to provide an overview and classification of current research approaches using models at runtime and to identify research areas not covered by models at runtime so far.     

一种Java API文档对异常描述不一致的自动检测方法

应用程序编程接口(Application Programming Interface,API)在软件开发以及代码复用中有着重要作用。然而,API代码和文档存在的不一致情况会误导API的使用者并降低软件开发效率及其稳定性等。针对Java API异常代码及其文档描述不一致的情况,提出了一种基于静态分析代码语法树及方法之间的调用关系的自动检测方法,为验证方法的有效性,利用JDK中的API源代码包及其相应文档作为测试对象根据实验结果。本方法的检测结果能达到71.5%的准确率以及85.9%的召回率,能够较为准确地识别API文档对程序异常描述不一致问题,对API文档的编写和维护具有指导性意义。     

Knowledge-based approaches in software documentation: A systematic literature review

ContextSoftware documents are core artifacts produced and consumed in documentation activity in the software lifecycle. Meanwhile, knowledge-based approaches have been extensively used in software development for decades, however, the software engineering community lacks a comprehensive understanding on how knowledge-based approaches are used in software documentation, especially documentation of software architecture design.ObjectiveThe objective of this work is to explore how knowledge-based approaches are employed in software documentation, their influences to the quality of software documentation, and the costs and benefits of using these approaches.MethodWe use a systematic literature review method to identify the primary studies on knowledge-based approaches in software documentation, following a pre-defined review protocol.ResultsSixty studies are finally selected, in which twelve quality attributes of software documents, four cost categories, and nine benefit categories of using knowledge-based approaches in software documentation are identified. Architecture understanding is the top benefit of using knowledge-based approaches in software documentation. The cost of retrieving information from documents is the major concern when using knowledge-based approaches in software documentation.ConclusionsThe findings of this review suggest several future research directions that are critical and promising but underexplored in current research and practice: (1) there is a need to use knowledge-based approaches to improve the quality attributes of software documents that receive less attention, especially credibility, conciseness, and unambiguity; (2) using knowledge-based approaches with the knowledge content in software documents which gets less attention in current applications of knowledge-based approaches in software documentation, to further improve the practice of software documentation activity; (3) putting more focus on the application of software documents using the knowledge-based approaches (knowledge reuse, retrieval, reasoning, and sharing) in order to make the most use of software documents; and (4) evaluating the costs and benefits of using knowledge-based approaches in software documentation qualitatively and quantitatively.     

在Python中结合doctest和Epydoc产生敏捷文档的一种方法

Python是一种敏捷开发项目经常采用的语言。本文介绍了在Python敏捷项目中结合类似epydoc文档系统，使在doctest单元测试同时能够产生同步的最新文档，比如常用的功能说明文档等，在敏捷开发中常被称作敏捷文档。     

A situational method for semi-automated Enterprise Architecture Documentation

The business capabilities of modern enterprises crucially rely on the enterprises’ information systems and underlying IT infrastructure. Hence, optimization of the business-IT alignment is a key objective of Enterprise Architecture Management (EAM). To achieve this objective, EAM creates, maintains and analyzes a model of the current state of the Enterprise Architecture. This model covers different concepts reflecting both the business and the IT perspective and has to be constantly maintained in response to ongoing transformations of the enterprise. In practice, EA models grow large and are difficult to maintain, since many stakeholders from various backgrounds have to contribute architecture-relevant information. EAM literature and two practitioner surveys conducted by the authors indicate that EA model maintenance, in particular the manual documentation activities, poses one of the biggest challenges to EAM in practice. Current research approaches target the automation of the EA documentation based on specific data sources. These approaches, as our systematic literature review showed, do not consider enterprise specificity of the documentation context or the variability of the data sources from organization to organization. The approach presented in this article specifically accounts for these factors and presents a situational method for EA documentation. It builds on four process-supported documentation techniques which can be selected, composed and applied to design an organization-specific documentation process. The techniques build on a meta-model for EA documentation, which is implemented in an EA-repository prototype that supports the configuration and execution of the documentation techniques. We applied our documentation method assembly process at a German insurance company and report the findings from this case study in particular regarding practical applicability and usability of our approach.     

On fuzzy repetitions detection in documentation reuse

Increasing complexity of software documentation calls for additional requirements of document maintenance. Documentation reuse can make a considerable contribution to solve this problem. This paper presents a method for fuzzy repetitions search in software documentation that is based on software clone detection. The search results are used for document refactoring. This paper also presents Documentation Refactoring Toolkit implementing the proposed method and integrated with the DocLine project. The proposed approach is evaluated on documentation packages for a number of open-source projects: Linux Kernel, Zend Framework, Subversion, and DocBook.     

Tania's Space

In this first person, narrative account, visual artist Richard Layzell explains how his work as Research Associate for ResCen (Centre for Research into Creation in the Performing Arts) has led to a series of enquiries into the documentation of his creative process, and in particular the development of a fictional persona, Tania, who has begun to play an integral part in his practice.     

Why and how of requirements tracing

While requirements traceability is explicitly required in US Department of Defense software contracts, it is often hard to sell in other situations. This article explains how Abbott Laboratories Diagnostics Division approaches traceability. To illustrate our program, we describe how we applied it to an R&D project to develop an embedded, real-time in vitro diagnostic instrument. The software is part of a system to test human body fluids for conditions such as cancer or hepatitis. We learned a great deal from this application and continue to experiment with and evolve the traceability-analysis process. In particular, we found that we must establish documentation rules and formats much earlier in the life cycle. Another lesson we learned is that traceability does cost. You need staff to support formal inspections or reviews. For most projects, you need some type of tool to assist in managing the trace matrices. We developed a relatively low-cost tool to handle our needs. Whatever the cost, it is important to include it as well as the costs for developing and maintaining procedures for documentation formats and generation, traceability analysis, and formal inspections. Our biggest lesson is that traceability is critical to project success. We believe it was one of the key factors in releasing our diagnostic instrument on time. Finally, we determined the conditions under which some type of traceability program is necessary     

Literate Programming System CDS

This paper presents a broad outline and some implementation techniques of the literate programming system CDS.Compared with the previous ones (e.g.WEB,Cweb),CDS has two main characteristics:1) A Chinese-English typesetting system was developed to produce the documentation.This makes the Chinese documentation possible.2) A suitable method for automatic formatting was introduced to generate the software documentation automatically.This frees the programmer from typesetting details while still allowing programmer‘s interference.     

LIY: learn-it-yourself software interfaces

An increasing number of people are becoming users of unfamiliar software. They can be genuinely "new" computer users or part of a growing group who are transferring skills and knowledge from a familiar product such as a word processor to a functionally similar, but different, unfamiliar one. The problem for users in this position is that they do not have access to training courses to teach them how to use such software and are usually forced to rely on text-based documentation. LIY is a method for producing computer-based tutorials to teach the user ofasoftware product.This paper describes how LIY is, in turn, (1) a method for application system design which recognizes the need for tutorial design (a task analysis and user interface specification provide information structures that are passed to the tutorial designer); (2) a support environment for the tutorial designer (in addition to prompting for courseware for nodes in the task analysis, LIY provides a ready-made rule base for constraining the degree of learner control available while the tutorial is in use. The designer is able to tailor this rule base for a specific tutorial); and (3) a tutorial delivery environment (the tutorial adapts to individual learners and offers a degree of learner control).     

基于CHNN聚类算法的款式部件生成模型

对智能化服装款式设计系统中的款式部件的自动获取功能进行了研究.采用基于连续Hopfield神经网络(CHNN)的聚类算法提出了一个款式部件的风格生成模型.提取表现部件造型特征的特征要素构造一个空间点集,利用CHNN网络对该点集进行聚类,分析部件类别与款式设计风格之间的关系,建立基于款式风格设计的部件搭配规则.并将该模型应用于款式的衣片部件上,实现了衣片部件的聚类.实验结果表明,该模型设计合理,分类清晰,具有可扩展性.     

面向概念的知识获取系统

本文提出的面向概念的知识获取系统是一个能理解基本逻辑和自然语言的知识获取环境.系统结合了人工智能(AI),面向对象的程序设计(oop)和逻辑程序设计(Lp)等技术.系统以概念为知识基元,由概念描述器(cd)予以描述.cd由一组概念特性、属性、逻辑约束和函数式等支持.概念集在知识库中是一个层次式的继承网络.系统主要用于辅助专家开发新系统的描述、定义和说明.也可对已有的系统、文本文件进行描述并用于教育.