research-article

Lessons from trying to develop a robust documentation exemplar

Authors:

Lynn Robert Carter,

Andreas KaratsolisAuthors Info & Claims

SIGDOC '09: Proceedings of the 27th ACM international conference on Design of communication

Pages 199 - 204

https://doi.org/10.1145/1621995.1622035

Published: 05 October 2009 Publication History

Abstract

Software system documentation has been an integral part of the development process since the first efforts to design and implement large and robust systems. However, the focus of this documentation typically has been limited to the production of discrete artifacts, despite the richness of data and genres that surround it. Efforts to develop a robust documentation exemplar - Della - have not been completely successful, mainly because the provided documentation was largely ignored by many students for simpler but less effective alternate designs. This paper will present, in addition to the lessons learned from the Della project, some insights into the direction software system documentation now should be taking in support of large and long-lived systems.

References

[1]

ACM SIGCHI. Bulletin. Vol. 21, No. 2 (Oct. 1989). New York: ACM Inc.

[2]

Carver, M. Video in Design Research: Methods, Novel Use, and Rationale. Masters Thesis. (May 2009). Pittsburgh: Carnegie Mellon University.

[3]

DeMarco, T. Software Engineering: An idea whose time has come and gone? IEEE Software. ISSN 0740-7459 (Jul./Aug. 2009), 96, 95. New York: IEEE Computer Society.

Digital Library

[4]

Geisler, C., Bazerman, C., Doheny-Farina, S., Gurak, L., Haas, C., Johnson-Eilola, J., Kaufer, D.S., Lunsford, A., Miller, C. IText -- Future Directions for Research on the Relationship between Information Technology and Writing. Journal of Business and Technical Communication. Vol. 15, No. 3 (July 2001), 269--308. Thousand Oaks: Sage Publications, Inc.

[5]

Hart-Davidson, W., Bernhardt, G., McLeod, M., Rife, M., and Grabill, J.T. Coming to Content Management: Inventing Infrastructure for Organizational Knowledge Work. Technical Communication Quarterly. Vol. 17, Issue 1 (Jan. 2008), 10 -- 34. Florence: Routledge.

[6]

Humphrey, W.A., A Discipline for Software Engineering. (1995). Indianapolis: Addison-Wesley.

Digital Library

[7]

Humphrey, W.A., PSP: A Self-Improvement Process for Software Engineers. (2005). Indianapolis: Addison-Wesley.

Digital Library

[8]

Johnson-Eilola, J. Datacloud: Expanding the Roles and Locations of Information. SIGDOC 2001 Conference Proceedings. (Oct. 2001), 47--54. New York: ACM Inc.

Digital Library

[9]

MacLean, A., Young, R.M.,&Moran, T.P. Design Rationale: The Argument Behind the Artifact. Proceedings of the SIGCHI conference on Human factors in computing systems: Wings for the mind. (Apr.--May 1989), 247--252. New York: ACM Inc.

Digital Library

[10]

Schank, R.C. Making Minds Less Well Educated Than Our Own. (2004), 282--299. Mahwah, New Jersey: Lawrence Erlbaum Associates, Inc.

[11]

Schlottman, F., Mitschele, A., and Seese, D. A Multi-objective Approach to Integrated Risk Management. Evolutionary Multi-Criterion Optimization. Vol. 3410/2005, (2005), 692--706. Berlin / Heidelberg: Springer.

Digital Library

[12]

Schön, D.A., The Reflective Practitioner: How Professionals Think in Action. (1983). New York: Basic Books, Inc.

[13]

Spinuzzi, C. Software development as mediated activity: applying three analytical frameworks for studying compound mediation. Proceedings of the 19th annual international conference on Computer documentation. (2001), 58--67. New York: ACM Inc.

Digital Library

[14]

Spinuzzi, C. Compound mediation in software development: Using genre ecologies to study textual artifacts. In Charles B.&David R. (Eds.), Writing selves/writing societies. (2003), 97--124. Fort Collins: The WAC Clearinghouse and Mind, Culture, and Activity. DOI= http://wac.colostate.edu/books/selves_societies

[15]

Sun Microsystems, Inc. Javadoc Tool. DOI= http://java.sun.com/j2se/javadoc/

Cited By

Kopczyńska SShi J(2023)Can Videos be Used to Communicate Non-functional Requirements? An Early Empirical Investigation2023 IEEE 31st International Requirements Engineering Conference (RE)10.1109/RE57278.2023.00040(305-310)Online publication date: Sep-2023
https://doi.org/10.1109/RE57278.2023.00040
Carter L(2021)Climbing out of a software black holeSoftware: Practice and Experience10.1002/spe.297052:2(319-336)Online publication date: 28-Mar-2021
https://doi.org/10.1002/spe.2970
Karras OSchneider K(2018)Software Professionals are Not Directors: What Constitutes a Good Video?2018 1st International Workshop on Learning from other Disciplines for Requirements Engineering (D4RE)10.1109/D4RE.2018.00011(18-21)Online publication date: Aug-2018
https://doi.org/10.1109/D4RE.2018.00011
Show More Cited By

Index Terms

Lessons from trying to develop a robust documentation exemplar

Recommendations

Evaluating usage and quality of technical software documentation: an empirical study
EASE '13: Proceedings of the 17th International Conference on Evaluation and Assessment in Software Engineering

Context: Software documentation is an integral part of any software development process. However, software practitioners are often concerned about the lack of usage and quality of documentation in practice. Unfortunately, in many projects, practitioners ...
Evolution Support by Homogeneously Documenting Patterns, Aspects and Traces
CSMR '02: Proceedings of the Sixth European Conference on Software Maintenance and Reengineering

The evolution of complex software systems is promoted by software engineering principles and techniques like separation of concerns, encapsulation, stepwise refinement, and reusability of design solutions. Design patterns capture the expertise for ...
Reverse Engineering and Design Recovery: A Taxonomy

The key to applying computer-aided software engineering to the maintenance and enhancement of existing systems lies in applying reverse-engineering approaches. However, there is considerable confusion over the terminology used in both technical and ...

Comments

Information & Contributors

Information

Published In

cover image ACM Conferences

SIGDOC '09: Proceedings of the 27th ACM international conference on Design of communication

October 2009

328 pages

ISBN:9781605585598

DOI:10.1145/1621995

General Chairs:
Brad Mehlenbacher
North Carolina State University, USA
,
Aristidis Protopsaltis
University of Reading, UK
,
Program Chairs:
Ashley Williams
Bridgeline Software, USA
,
Shaun Slattery
DePaul University, USA

Copyright © 2009 ACM.

Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than ACM must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected]

Sponsors

Publisher

Association for Computing Machinery

New York, NY, United States

Publication History

Published: 05 October 2009

Permissions

Request permissions for this article.

Request Permissions

Check for updates

Author Tags

Qualifiers

Research-article

Conference

SIGDOC '09

Sponsor:

SIGDOC '09: The 27th ACM International Conference on Design of Communication

October 5 - 7, 2009

Indiana, Bloomington, USA

Acceptance Rates

Overall Acceptance Rate 355 of 582 submissions, 61%

Contributors

Other Metrics

View Article Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

7
Total Citations
View Citations
149
Total Downloads

Downloads (Last 12 months)6
Downloads (Last 6 weeks)0

Reflects downloads up to 09 Jan 2025

Other Metrics

View Author Metrics

Citations

Cited By

Kopczyńska SShi J(2023)Can Videos be Used to Communicate Non-functional Requirements? An Early Empirical Investigation2023 IEEE 31st International Requirements Engineering Conference (RE)10.1109/RE57278.2023.00040(305-310)Online publication date: Sep-2023
https://doi.org/10.1109/RE57278.2023.00040
Carter L(2021)Climbing out of a software black holeSoftware: Practice and Experience10.1002/spe.297052:2(319-336)Online publication date: 28-Mar-2021
https://doi.org/10.1002/spe.2970
Karras OSchneider K(2018)Software Professionals are Not Directors: What Constitutes a Good Video?2018 1st International Workshop on Learning from other Disciplines for Requirements Engineering (D4RE)10.1109/D4RE.2018.00011(18-21)Online publication date: Aug-2018
https://doi.org/10.1109/D4RE.2018.00011
Karras O(2018)Software Professionals’ Attitudes Towards Video as a Medium in Requirements EngineeringProduct-Focused Software Process Improvement10.1007/978-3-030-03673-7_11(150-158)Online publication date: 3-Nov-2018
https://doi.org/10.1007/978-3-030-03673-7_11
Karras OUnger-Windeler CGlauer LSchneider K(2017)Video as a By-Product of Digital Prototyping: Capturing the Dynamic Aspect of Interaction2017 IEEE 25th International Requirements Engineering Conference Workshops (REW)10.1109/REW.2017.16(118-124)Online publication date: Sep-2017
https://doi.org/10.1109/REW.2017.16
Karras OKiesling SSchneider K(2016)Supporting Requirements Elicitation by Tool-Supported Video Analysis2016 IEEE 24th International Requirements Engineering Conference (RE)10.1109/RE.2016.10(146-155)Online publication date: Sep-2016
https://doi.org/10.1109/RE.2016.10
Fricker SSchneider KFotrousi FThuemmler C(2016)Workshop videos for requirements communicationRequirements Engineering10.1007/s00766-015-0231-521:4(521-552)Online publication date: 1-Nov-2016
https://dl.acm.org/doi/10.1007/s00766-015-0231-5

View Options

Login options

Check if you have access through your login credentials or your institution to get full access on this article.

Full Access

Get this Publication

View options

PDF

View or Download as a PDF file.

eReader

View online with eReader.

Media

Figures

Other

Tables

View Table of Contents