Creating and evolving developer documentation
115
Citation
19
Reference
10
Related Paper
Citation Trend
Abstract:
Developer documentation helps developers learn frameworks and libraries. To better understand how documentation in open source projects is created and maintained, we performed a qualitative study in which we interviewed core contributors who wrote developer documentation and developers who read documentation. In addition, we studied the evolution of 19 documents by analyzing more than 1500 document revisions. We identified the decisions that contributors make, the factors influencing these decisions and the consequences for the project. Among many findings, we observed how working on the documentation could improve the code quality and how constant interaction with the projects' community positively impacted the documentation.Keywords:
Internal documentation
Technical documentation
Software documentation
Code (set theory)
Complete and up-to-date documentation is essential for efficient data analysis in a large and complex collaboration like CMS. Good documentation reduces the time spent in problem solving for users and software developers. The scientists in our research environment do not necessarily have the interests or skills of professional technical writers. This results in inconsistencies in the documentation. To improve the quality, we have started a multidisciplinary project involving CMS user support and expertise in technical communication from the University of Turku, Finland. In this paper, we present possible approaches to study the usability of the documentation, for instance, usability tests conducted recently for the CMS software and computing user documentation.
Software documentation
Technical documentation
Internal documentation
User analysis
Cite
Citations (1)
This study suggests that computer documentation is a complex technical communication genre, encompassing all the texts that mediate between complex human activities and computer processes. Drawing on a historical study, it demonstrates that the varied forms given to documentation have a long history, extending back at least to the early days of commercial mainframe computing. The data suggests that (1) early forms of computer documentation were borrowed from existing genres, and (2) official and unofficial documentation existed concurrently, despite efforts to consolidate these divergent texts. The study thus provides a glimpse into the early experimental nature of documentation as writers struggled to find a meaningful way to communicate information about their organization's developing computer technology.
USable
Technical documentation
Software documentation
Internal documentation
Documentation science
Cite
Citations (21)
Program documentation is a vital source of information for software engineers charged with making changes to complex applications. Test documentation can be used to help future stakeholders understand the rationale behind the testing effort. This panel will discuss some of the similar features and salient differences between program documentation and test documentation. Although both types of documentation are usually written by and for different groups of people (for reasonable-sized projects), there is enough overlap that each could be improved by studying the communication strategies of the other.
Software documentation
Internal documentation
Technical documentation
Cite
Citations (0)
In the Spring 1973 of the Journal, Mr. Petito presented two closely related lectures in note form on the development of manuals, as given at an AMA seminar. The present paper develops computer software documentation with reference to types of documentation, documentation library, and documentation standards.
Software documentation
Technical documentation
Internal documentation
Cite
Citations (1)
The purpose of technical documentation for end-users (in printed or on-screen form) is to enable people to achieve their goals by working with a product effectively, efficiently and in a safe manner. Technical documentation that has to be read by end users provides a special demand because the way of thinking and the vocabulary of a typical end user is different from that of a technical expert. Six documentation anti-patterns are discussed in this paper. They address the structure of the documentation, the organization of the access to its contents and the language used in the documentation. In addition to the discussion of anti-patterns, the article contains suggestions for better solutions.
Technical documentation
User analysis
Software documentation
Internal documentation
Cite
Citations (3)
This study suggests that documentation is a complex technical communication genre, encompassing all the texts that mediate between complex human activities and computer processes. Drawing on a historical study, it demonstrates that the varied forms given to documentation have a long history, extending back at least to the early days of commercial mainframe computing. The data suggest that (1) early forms of documentation were borrowed from existing genres, and (2) official and unofficial documentation existed concurrently, despite efforts to consolidate these divergent texts. The study thus provides a glimpse into the early experimental nature of documentation as writers struggled to find a meaningful way to communicate information about their organization's developing computer technology.
Technical documentation
USable
Software documentation
Internal documentation
Documentation science
Technical communication
Cite
Citations (12)
Technical documentation
Internal documentation
Software documentation
User analysis
Technical communication
Cite
Citations (0)
Technical documentation
User analysis
Software documentation
Internal documentation
Cite
Citations (5)
(Good) Software documentation provides developers and users with a description of what a software system does, how it operates, and how it should be used. For example, technical documentation (e.g., an API reference guide) aids developers during evolution/maintenance activities, while a user manual explains how users are to interact with a system. Despite its intrinsic value, the creation and the maintenance of documentation is often neglected, negatively impacting its quality and usefulness, ultimately leading to a generally unfavourable take on documentation. Previous studies investigating documentation issues have been based on surveying developers, which naturally leads to a somewhat biased view of problems affecting documentation. We present a large scale empirical study, where we mined, analyzed, and categorized 878 documentation-related artifacts stemming from four different sources, namely mailing lists, Stack Overflow discussions, issue repositories, and pull requests. The result is a detailed taxonomy of documentation issues from which we infer a series of actionable proposals both for researchers and practitioners.
Software documentation
Internal documentation
Technical documentation
User analysis
Empirical Research
Cite
Citations (140)
In spite of numerous research efforts, much software documentation continues to be unusable and/or unused. Current formulation of the software documentation problem is described in terms of two sets of problem variables characterizing the documentation products and processes. This research shows that attributes of the computing setting affect the documentation products and processes. The setting attributes are therefore an important set of problem variables that need to be considered when developing solutions to the software documentation problem. The study empirically examines the effect of three setting attributes on the patterns of production and consumption of documents in real software projects. It proposes and validates a set of hypotheses that define relationships between the documentation settings, products, and processes. The study also shows that accounting for the setting attributes reveals that the software documentation problem is inherently an open system problem. Open systems assume that the information about the world being modeled is never complete. The study indicates that current solution approaches to the documentation problem are solutions only in the closed system perspective. Applying current solutions of the documentation problem does not and cannot therefore generate effective solutions. The verified hypotheses define empirically grounded relationships between the documentation settings, processes, and products. It suggests a documentation model that constitutes a new solution approach to the documentation problem. The model describes mechanisms to achieve solution alternative (local closures) for the software documentation problem. It is therefore a solution approach that addresses the documentation problem as it has always been: an open system problem. (Copies available exclusively from Micrographics Department, Doheny Library, USC, Los Angeles, CA 90089-0182.)
Software documentation
Internal documentation
Technical documentation
Cite
Citations (1)