Domain Modules (Course)

This course teaches a contextual approach to describe a high-level view of how and why people engage with a system, as described in my 2023 article.

Learning “who and why” is an enabler for better conversations, for better decisions, and for documentation that addresses the needs of people.

Instructor-led, live online course, 12 hours in class, offered at Polytechnic University of Porto since 2023.

Learning objectives

At the end of the module, students will be able to:

• Read UML class diagrams.
• Refine class diagrams into business descriptions with use cases.
• Create business descriptions from interacting actors and their motivations.
• Identify business concepts and their relations.
• Apply domain models to improve traditional documents.

Why am I teaching this?

I have mostly worked in large systems that evolved over time, often in disruptive ways. Altitude Software had a complex suite of technical products, while Farfetch has a complex business supported by complex software. These systems are difficult to understand and difficult to explain, to the point that it took years to explain some parts in a satisfactory way.

The software practice of Domain-Driven Design uses domain models to enable fruitful conversations between software developers and business stakeholders. I explored how domain models could grow into standalone artifacts that teach the purpose of a business or system to anyone.

With access to experts and technical artifacts, technical writers take one or two days to gather information and create a couple of high-level structured pages. Having that knowledge structured empowers technical writers to:

• Talk effectively with both technical and business people, exposing gaps in the communication.
• Start new projects with a stronger sense of purpose that guides prioritization and artifact choices, instead of drowning in the details.
• Identify and explain major concepts as perceived by users and stakeholders.
• Create tutorials that address business needs instead of just exercising the system.
• Create better references by exposing the business purpose of technical details.

In summary, domain models enable writers to quickly write better documentation.

What happens in class?

The course is organized in five lessons:

1. We learn the benefits of domain models for technical writing.
2. We learn enough of UML class diagrams to create useful models, and we practice using the open source application AsciidocFX.
3. We learn to create contextual modules, as described in the ISTC article, with practice.
4. We learn to create conceptual models, as described in the ISTC article, with practice.
5. We learn how to use very technical models to discover the business they implement, as described in the 2019 presentation at the TCeurope Colloquium.

The course only works if students engage in class and outside class, by pre-reading texts and completing assignments, which are debriefed in class. In the University course, students that engage in class get a passing grade. A final exercise where students apply domain models to a topic they choose provides further feedback and the possibility of a higher grade.

Course history

This course start as presentation of what would become Lesson 5 in TEeurope'19. As my practice matured, I presented the contextual approach at TCUK'23. The materials grew into a module with practice for the Polytechnic University of Porto, introduced when we restructured the Postgraduate Diploma on Technical Communication for the academic year 2023/2024.

Available yearly or on demand

This training is an instructor-led module available live online or on premises. The training room requires a projector. Students require computers with the open source application AsciidocFX.

In 2023/2024, this training was offered between 15-Dec and 19-Jan (4x3h) for €125 as an instructor-led, live online course, integrated in the Postgraduate Diploma on Technical Communication. A similar offer is expected for 2024/2025.

Contact me for details: px@acm.org — LinkedIn — +351 91 784 2996