Member Avatar for st_uni-trier

Hi,

we, the Software Engineering Group at Trier University (Germany), are currently
conducting a survey on the use of sketches and diagrams in software
development. We want to gain deeper insights into the work of software practitioners
(developers, testers, architects, etc.) to call attention to their
actual work practices, which we think is rarely done in academic research.

It is difficult for us to reach software practitioners, therefore I post my call for participation here.
Our short online survey (5-10 minutes) is available here:

We can also discuss how and why you create and use sketches and diagrams when developing software in this thread.
Thanks in advance for your participation!

  • 2 Contributors
  • 2 Replies
  • 271 Views
  • 12 Hours Discussion Span
  • Latest Post Latest Post by st_uni-trier

Dani AI

Generated

A short practical note for 's survey: sketches and diagrams serve three distinct roles - exploration (thinking), alignment (communication), and recording (decisions). Quick hand-drawn sketches are best for exploring alternatives; tidy, versioned diagrams work when multiple people or future maintainers depend on the artifact. As observes, practitioners often prioritize tests and reading code; use sketches to reduce ambiguity so tests and reviews are more effective, not to replace them.

A lightweight workflow to apply immediately:

  1. sketch on paper or a whiteboard to surface assumptions;
  2. photograph and attach the image to the related issue or PR;
  3. if the diagram will be reused, convert it to a text-based format and commit it to the repo;
  4. label each diagram with purpose, scope and date. Text-based generators keep diagrams editable and reviewable; a minimal PlantUML example that mirrors a quick sequence sketch:
@startuml
actor Client
participant API
database DB

Client -> API: POST /order
API -> DB: INSERT order
DB --> API: OK
API --> Client: 201 Created
@enduml

Troubleshooting and practical tips: when diagrams drift from implementation, require updates in the PR; use diagrams to make boundary conditions and timing explicit (sequence/state diagrams help reason about races); for API changes, capture request/response shapes alongside the diagram. Keep notation plain - boxes and arrows with short labels will solve most communication problems. If a sketch is only for thinking, keep it ephemeral to avoid maintenance debt.

Rules of thumb: pick the simplest representation that solves the immediate problem; promote a diagram into the repo only when it guides implementation, testing or handover; always annotate author/purpose/date. Empirical work like 's helps close the gap between academic prescriptions and daily practice.

Recommended Answers

All 2 Replies

Member Avatar for mike_2000_17

The survey is a bit weirdly formulated. The questions seem to refer to the "last sketch/diagram" that I made. That could happen to be anything from the most involved sketch that I ever drew to the most trivial doodle on a random piece of paper. I went by the assumption that the questions refer to the sketches / diagrams I usually draw on average.

To be honest, as a general remark about the use of diagrams and especially UML, I think academia focuses way too much attention on that. Although visual representation of code is important and useful, it is not critical. The average practitioner probably spends far more time worrying about quality assurance (QA) for his software than he worries about design methodologies and those diagram rules that academics dream up. I know that for me, I draw diagrams occasionnally to either make a plan for a future piece of architecture or to make a visual summary of existing code, but mostly, I rely on generated documentation (e.g., doxygen, call-graphs, etc.) and reading source code. But overall, that representes a very tiny chunk of my time. Worrying about how to prove or test the correctness and robustness of the software is the thing I preoccupies me every waking moment. If academics have decent methodologies and insights on quality assurance, I'm all ears, but I've been tuned out of any discussions about UML diagrams and stuff for years, because it's really not that important, all things considered.

Member Avatar for st_uni-trier

Hey!

Thanks for your remarks.

That could happen to be anything from the most involved sketch that I ever drew to the most trivial doodle on a random piece of paper.

We are aware of this problem. However, we think that we get a more realistic view if we ask for the last sketch and collect enough answers. Just imagine the following scenario: If we would ask "Do you brush your teeth regularly?" almost everyone would answers with "Yes". By asking "Did you brush your teeth this morning?" the results should be more interesting...

To be honest, as a general remark about the use of diagrams and especially UML, I think academia focuses way too much attention on that.

Well, that's why we are conducting this survey ;-). There have been some studies over the last years on the use of UML in practice. If you like to, I can send you an interesting paper on this topic.

Be a part of the DaniWeb community

We're a friendly, industry-focused community of developers, IT pros, digital marketers, and technology enthusiasts meeting, networking, learning, and sharing knowledge.