Sketches and Diagrams in Practice (SE'15)
1 like484 views
The document discusses the importance of sketches and diagrams in software engineering, emphasizing their frequent use among developers for understanding and documenting software. A study involving 394 software practitioners revealed that sketches are typically created and revised quickly, are often informal, and are perceived as helpful for understanding source code. The findings highlight the need for better tools to support the integration and archiving of these visual aids in the software development process.
![Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice
Introduction
3
Past studies:
Sketches and diagrams important in daily work of software developers
Purpose: Understanding,
designing, communicating
[Cherubini07]
Depict mental model
of software
[LaToza06]
Teams improvise representations,
sketches/diagrams often informal
[Dekel07, Petre13]
Medium: Whiteboard, paper,
computer [Cherubini07, Walny11]
Psychology: Sketching augments
information processing, sketches
are sources of creativity
[Goldschmidt03, Tversky03]](https://image.slidesharecdn.com/se15-sketches4-3-150323104253-conversion-gate01/85/Sketches-and-Diagrams-in-Practice-SE-15-3-320.jpg)
![Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice
Archiving – Why?
23
If the sketch has been archived or will be archived, why do you want to
keep it?
Documentation Future Use
Understanding Visualization
"It will be difficult
to understand the
code without the
diagram."
"[The code] can be quickly
understood due to the
visual representation
without hours of digging
through complex source
code."
"[The sketch] shows
concepts that are not
directly visible from
code."](https://image.slidesharecdn.com/se15-sketches4-3-150323104253-conversion-gate01/85/Sketches-and-Diagrams-in-Practice-SE-15-23-320.jpg)
![Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice
Archiving – Why not?
25
If the sketch has not been archived and won't be archived, why do you not
want to keep it?
Served its purpose Substituted
Outdated Technical Issue
"I do want to keep the
sketch, but I have no
way to archive
whiteboard drawings."
"There is no good
option to keep the
sketch together
with source code."
"In case there
was an easy way to
combine both, code [...]
and sketch I
might have thought
about archiving it."](https://image.slidesharecdn.com/se15-sketches4-3-150323104253-conversion-gate01/85/Sketches-and-Diagrams-in-Practice-SE-15-25-320.jpg)
![Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice
Conclusion
• Software documentation is frequently poorly written and out of
date
[Forward02, Lethbridge03]
• Sketches and diagrams could serve as a supplement to conventional
documentation
• Software practitioners are willing to keep their sketches and
diagrams
• Better tool support needed for archiving and retrieving sketches/
diagrams related to source code artifacts
• Tools should support evolution of sketches/diagrams (and software)
29](https://image.slidesharecdn.com/se15-sketches4-3-150323104253-conversion-gate01/85/Sketches-and-Diagrams-in-Practice-SE-15-29-320.jpg)
Sketches and Diagrams in Practice (SE'15)
- 1. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice @s_baltes s.baltes@uni-trier.de Sketches and Diagrams in Practice Sebastian Baltes and Stephan Diehl University of Trier, Germany Software Engineering 2015 Gesellschaft für Informatik 19. März 2015, Dresden
- 2. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Sketches and Diagrams 2 Sketch Diagram informal formal
- 3. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Introduction 3 Past studies: Sketches and diagrams important in daily work of software developers Purpose: Understanding, designing, communicating [Cherubini07] Depict mental model of software [LaToza06] Teams improvise representations, sketches/diagrams often informal [Dekel07, Petre13] Medium: Whiteboard, paper, computer [Cherubini07, Walny11] Psychology: Sketching augments information processing, sketches are sources of creativity [Goldschmidt03, Tversky03]
- 4. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Our Goal 4 Our goal: Thorough description of how sketches and diagrams are used in software engineering practice Existing studies: • Concentrated on certain aspects • Single companies • Academic environment • Some had small number of participants Better tool support for integrating sketches and diagrams into software development process
- 5. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Our Goal 5 Our goal: Thorough description of how sketches and diagrams are used in software engineering practice Existing studies: • Concentrate on certain aspects • Single companies • Academia • Some had small number of participants Better tool support for integrating sketches and diagrams into software development process
- 6. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Research Design How to describe sketches and diagrams in SE practice? 6
- 7. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Research Design 7 Existing Studies Exploratory Field Study 11 Dimensions 3 companies 13 developers 47 sketches Sketch Medium Context Contributors Relation to Source Code UML-Elements Formality Archiving LifespanRevision Purpose Effort Online Survey purpose, media, formality, etc.
- 8. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Online Survey • Target population: "software practitioners" • Concise: • ~10 minutes to complete • 28 questions, 15 about last sketch • Recruiting: • Network of colleagues and contacts • Social networks • IRC channels and online communities • Directly contacted software companies • Article on major German IT news website 8
- 9. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Participants • n=394 • 32 countries • 54% Germany 15% North America • 52% software developers, 22% software architects • Time spent developing software: 80% (median) • Professional work experience: 10 years (median) • Software projects from various application areas 9
- 10. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Results 10
- 11. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Creation and Usage 11 When did you create your last sketch/diagram? When did you use the last sketch/diagram created by some else? looked at, modified, extended <10 minutes several minutes several hours several days several weeks >1 year several months 0 20 40 60 80 100 120 140 160 180 ago 24% 27% same day 63% 61% one week 85% 78% one month Takeaway 1: Creating own sketches and using sketches created by others are frequent tasks among software practitioners.
- 12. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Media 12 Whiteboard (40%) Paper (18%) Computer (39%) Analog (58%) Digital (42%) What medium did you use to create the sketch/diagram? Tablet (0.8%) E-Whiteboard (1.5%)
- 13. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Purpose 13 The sketch/diagram helped me to… (multiple answers possible) …design a new architecture (52%) …design new features (48%) …explain an issue to someone else (46%) …analyze requirements (45%) …understand an issue (44%) 0 50 100 150 200 250 300 350 Design Explain Understand Requirements 75% 60% 56% 45%
- 14. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Purpose 14 The sketch/diagram helped me to… (multiple answers possible) …design a new architecture (52%) …design new features (48%) …explain an issue to someone else (46%) …analyze requirements (45%) …understand an issue (44%) 0 50 100 150 200 250 300 350 Design Explain Understand Requirements 75% 60% 56% 45%
- 15. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Effort and Revision 15 How much effective work time went into the creation and revision of the sketch/diagram up to now? 0 20 40 60 80 100 120 140 160 180 <10 minutes several minutes several hours several days > 5 days work time 93% less than 8 hours 68% less than 1 hour Takeaway 2: Most sketches are created in less than one hour and are revised at least once. Revision: 15% revised once, 74% multiple times
- 16. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Lifespan 16 Please try to estimate the lifespan of the sketch/diagram (how long did/will you use it)? 0 10 20 30 40 50 60 70 80 90 <10 minutes ended immediately several minutes several hours several days several weeks several months >1 year lifespan 30% less than one day 65% at least several days 48% at least several weeks Takeaway 3: Almost half of the sketches are used for at least several weeks.
- 17. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Formality and UML 17 Formality: (6-point Likert scale (0-5) from "very informal" to "very formal") Please try to specify the formality of your sketch/diagram. UML: (6-point Likert scale (0-5) from "no UML elements" to "only UML elements") To which degree does the sketch/diagram contain UML elements? 68% informal 40% no UML 9% solely UML 48% some UML UML FOR 200 100 0 100 Count 0 1 2 3 4 5Var. Count 100 0 100 200 0 1 2 3 4 5 HEO HES Var. Count Formality UML Takeaway 4: The majority of sketches and diagrams are informal. If UML is used, it is often mixed with other notations.
- 18. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Relation to Source Code 18 Please select the software artifact(s) to which the content of the sketch/diagram is related? (multiple answers or no answer possible) Level of abstraction 0% 5% 10% 15% 20% 25% Statements Attributes Methods Classes Packages Projects 9% 8% 20% 23% 17% 19% Most specific artifact:
- 19. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Relation to Source Code 19 Please select the software artifact(s) to which the content of the sketch/diagram is related? (multiple answers or no answer possible) Level of abstraction 0% 5% 10% 15% 20% 25% Statements Attributes Methods Classes Packages Projects 9% 8% 20% 23% 17% 19% Most specific artifact:
- 20. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Relation to Source Code 20 Count 100 0 100 200 0 1 2 3 4 5 HEO HES Var. Count 100 0 100 200 0 1 2 3 4 5 HEO HES Var. Count Help self Help others Help self: Do you think that the sketch/diagram could help you in the future to understand the related source code artifact(s)? Help others: (6-point Likert scale (0-5) from "It will definitely not help " to "It will definitely help") … help other software developers … 52% and 47% Likert 4-5 Takeaway 5: About half of the sketches are rated as helpful to understand the related source code artifact(s) in the future.
- 21. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving 21 58% archived 1. Has the sketch/diagram been archived or will it be archived? 2. If the sketch has been archived or will be archived, why do you want to keep it? 3. If the sketch has not been archived and won't be archived, why do you not want to keep it? Three questions: • Answers analyzed using an approach based on open coding • Extracted four categories for the answers to each question • One category for archiving practice
- 22. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving 22 Not archived (62%) Archived (38%) Not archived (6%) Archived (94%) Analog (58%) Digital (42%) Takeaway 6: Most digital sketches, but also more than one third of the analog sketches, are archived. Whiteboard (40%) Paper (18%) Computer (39%) Tablet (0.8%) E-Whiteboard (1.5%)
- 23. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving – Why? 23 If the sketch has been archived or will be archived, why do you want to keep it? Documentation Future Use Understanding Visualization "It will be difficult to understand the code without the diagram." "[The code] can be quickly understood due to the visual representation without hours of digging through complex source code." "[The sketch] shows concepts that are not directly visible from code."
- 24. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving – Why? 24 If the sketch has been archived or will be archived, why do you want to keep it? Documentation Future Use Understanding Visualization Takeaway 7: Sketches are kept, because they document software, visualize it, and support its understanding.
- 25. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving – Why not? 25 If the sketch has not been archived and won't be archived, why do you not want to keep it? Served its purpose Substituted Outdated Technical Issue "I do want to keep the sketch, but I have no way to archive whiteboard drawings." "There is no good option to keep the sketch together with source code." "In case there was an easy way to combine both, code [...] and sketch I might have thought about archiving it."
- 26. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Archiving – How? 26
- 27. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Summary 27
- 28. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Takeaways 28 • Creating own sketches/diagrams and using sketches/diagrams created by others are frequent tasks among software practitioners • Most sketches/diagrams are created in less than one hour and are revised at least once after creation • Almost half of the sketches/diagrams are used for at least several weeks • Majority of sketches/diagrams are informal • About half of the sketches/diagrams are rated as helpful to understand the related source code artifact(s) in the future • Most digital sketches/diagrams, but also more than one third of the analog ones, are archived • Sketches/diagrams document the implementation, visualize it, and support its understanding 1 2 3 4 5 6 7
- 29. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Conclusion • Software documentation is frequently poorly written and out of date [Forward02, Lethbridge03] • Sketches and diagrams could serve as a supplement to conventional documentation • Software practitioners are willing to keep their sketches and diagrams • Better tool support needed for archiving and retrieving sketches/ diagrams related to source code artifacts • Tools should support evolution of sketches/diagrams (and software) 29
- 30. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Future Work 30 Recommendations on how to create, augment, or annotate sketches so that they can serve as a valuable software documentation. What distinguishes helpful from not helpful sketches? Do (informal) visualizations for certain source code artifacts share common characteristics? What context information is required to understand sketches later?
- 31. Software Engineering GroupSebastian Baltes – Sketches and Diagrams in Practice Questions? 31 Survey data and questionnaire available at: ! http://st.uni-trier.de/! survey-sketches @s_baltes s.baltes@uni-trier.de Consist ent * Complete * WellDocume nted*Easyto R euse* * Evaluate d *FSE* Artifact * AEC Video of prototype available at: ! http://st.uni-trier.de/! sketchlink SketchLink