Domain Modeling as Documentation Development
Domain modeling is for business users, by business users, and in the language of business.
This approach has no need for expensive modeling tools or complicated formalism.
There is no silver bullet or automated tool (yet) for whole language writing and business analysis.
Domain modeling is not a code-first approach! Code comes later in this paradigm.
This approach makes modeling no longer the exclusive province of the code team.
Class diagrams are not the only or even the most effective type of modeling artifact.
Class diagrams can tend to harden the group's thinking into static objects at the expense of the relationships among them, before these relationships are understood and explored.
Modeling both actors, entities, and abstract objects as class-object boxes can obscure type distinctions that are valuable in discerning relationships.
Good writing uses active verbs. A model that is all nouns (class objects) is just a list and not a story.
Object associations can only express linking verbs. The business model needs active verbs, and thus use cases, to define its actor and entity objects.
An effective domain model will inform and guide both system and data architecture and data models.
However, a domain model is neither a data model nor a codeable object model.
The end product of the domain model is directed at the business audience in their own language.
Documentation tends to grow organically as new features are added.
Emphasis tends toward static reference and/or stepwise procedures.
Documents can be missing core concepts, abstract ideas, and key navigation.
Complex and branching flows may be missing, obscured, or difficult to express.
The audience is assumed and implied, but users (actors) may not be explicitly defined or analyzed.
There may be little or no systematic approach to information architecture (documents with a strong outline probably have well-defined implicit domain models).
Documents tend to grow large, deep, and flat, without much navigation.
Documents can become static copies of the user interface, both redundant and quickly outdated.
Glossaries tend to grow into long flat tables, diluting or obscuring relationships among terms when sorted alphabetically.
Big and important ideas can be obscured by lots of little ideas.
The less you can see what's important, the more you will be driven to document everything.
Your information architecture is systematic in covering the domain space.
Your audience is well-defined and analyzed so it can be targeted.
Emphasis is on relationships among terms and the ideas they represent.
Documentation is well-structured and easy to navigate.
Documentation is just as big, and only as big, as it needs to be.
Some documentation needs to be big enough to be impressive when printed. Big documents need even better navigation and structure.
Documentation adds value beyond a static demo.
Core concepts and abstract ideas are clearly visible.
Both writers and users can separate big ideas from smaller ones to see what's important.
It may help to think of domain modeling as a simple and structured way to write a research paper, or in this case a user guide.
CHOOSE A TOPIC: Define your domain and state its boundaries. Be clear on limits to scope.
FIND INFORMATION: Use documents you already have as source data. Identify other team members and their documents who cover the subject matter.
MAKE AN OUTLINE: Use the object types defined in the modeling workflow below.
ORGANIZE YOUR NOTES: Put all your source information where you can find it.
FIRST DRAFT: For each object type, draft a model using the workflow below.
REVISE: Return to previous type sections and refactor your work iteratively.
REVIEW: Validate your model by submitting it to a formal review process.
REVISE AGAIN: Expect your model to change as you and your reviewers discover new objects and relationships.
FINAL PRODUCT: Meet the goal of completing each workflow to the Rule of 3-7.
Use cases are ACTION VERBS in ACTIVE VOICE.
Each use case must have an actor as the subject. Most use cases have an entity as the object of the verb.
Review/Mine User Interface (screenshot & TOC)
Define Workflow Types (tabs)
Map UI elements into Use Cases & Workflows
The "coffee break test" defines the use case boundary.
Would the user get up to take a coffee break at this step?
If no, it is an activity inside a use case. If yes, it is a boundary between use cases in a workflow.
Define each use case as a sentence with a strong active verb.
Do not use the static or linking verbs of "to be", since they describe relationship (association) and not action (use case).
Use workflows to define and discover new and related use cases.
Generalize related use cases into a main flow and alternate flows.
Consider and invert passive voice when extracting use cases.
Define missing use cases by gaps in the workflow, or by actors in the workflow without a use case.
Refactor and map found use cases into workflows.
Goal: 5-9 Workflows with 5-9 use cases per workflow. Expect to refactor into scenarios.
Workflows are sequences of use cases: groups of sentences with a subject, a verb, and an object. Any of these elements may have attributes; static "being" verbs express the relationships among them.
Add direction arrows to use case associations
Refactor initial workflow groups into sequential flows
Keep workflows above the use case level; refactor lower-level activities into a given use case
visually model use cases as flowcharts with a beginning, middle, and end
watch for loops and branches: simplify with higher-level abstract use cases
interview/demo SMEs on typical scenarios and user tasks
look/listen for SME terms not captured in the domain model
observe where the actor changes in the use case flow
use swimlanes to break up the flow by actor
refactor long, deep, and/or branching workflows until they meet the Rule of 3-7
model interruptions and handoffs as workflow dependencies
identify all possible start and end points for a given actor
Goal: 3-9 workflows, at least one per actor, covering all use cases and entities
Features represent high-level business requirements in the same way that UI elements represent fine-grained business requirements.
Review/mine sales, presales, marketing and other feature listings
map features to domain elements
trace each feature to a use case
consider unmapped use cases as hidden feature requirements
define missing and hidden features
Return to entities and use cases to see which objects might better represent requirements
add use cases for missing features
refactor and map feature requirements into use cases
GOAL: High-level features trace to a workflow with a use case, actor(s), and entities/attributes. Fine-grained features trace to use cases and entity attributes.
Follow the Rule of 3-7 to organize and nest ideas. Construct a nested outline 3-7 levels deep, with 3-7 items per level. More than that may be too much detail and is almost certainly too complex.
Present your introduction by FEATURE REQUIREMENTS
Express features as problems your system solves for the user.
Organize document(s) by ACTOR. Give each user only what they do.
Include only your highest-level ENTITIES in the introduction.
Organize chapters by WORKFLOW. Don't jump around. Hyperlinks can help, but efficient users follow a workflow and the guide should support this.
Organize sections by USE CASE. Each is a step-by-step procedure.
Revise your writing, refactor your domain objects, and iterate through review cycles until you have achieved the Rule of 3-7 in covering your defined domain.
GOAL: You are done when 3-7 users (not just one) say "AHA!"
From each object type, list and define your 3-7 (or more) core objects as name:description.
This list is both your glossary, your index, and your model's data dictionary.
Make sure your document's table of contents and index reflect these core terms.
Work with users to collect related terms and synonyms for domain objects. Index these as See Also entries back to the domain object name.
Tag related terms in the glossary so that they are distinct from meaningful domain objects.
Do not index related terms except as See Also. Index only domain objects defined in your model.
Check your model for orphan objects without associations, and either associate them or delete them.
Check the glossary to make sure each object definition refers to its primary relationships.
Check the number of index entries against your glossary list. Are any glossary terms (domain model objects) not included in the index? If not, why not?
List 3 core workflows and 3 use cases, actors, and entities for each. This is your test set.
Ask readers to review the document for 30 seconds. Ask them what they read. See how well they can describe your 3 core workflows and their content.
Give a reader one of your core objects (ideas) and ask them to find it in the document. Give them 3 minutes and watch how they look for it. If they can't find it in 3 minutes, rework your navigation.
Ask a reader to work through the user guide for no more than 30 minutes and to note how many use cases and workflows they covered. See if your users can cover 3 core workflows in 30 minutes or less. That's as much time as a reader will spend at one session on documentation, so make it count.
Documentation may be widely known to be of poor quality, but it may not be clear why or how to fix it
Documentation is unwieldy, quickly outdated, and costly to maintain
Spreading the workload across different experts can lead to inconsistent and/or incomplete content
Subject matter experts (SMEs) can assume knowledge of key concepts so that they are not explicitly stated
The UI itself may not be following user workflows, so that the doc doesn't either
Managers seeking to address user problems without a systems model can unintentionally compound them with more rounds of organic growth
One document tries to serve all audiences and satisfies few or none
Users without core domain knowledge may struggle with basic core concepts
Users will mistrust and abandon incomplete or inconsistent documentation
Users abandon documentation that is too big, too long, and too hard to skim
If users don't see how to find an answer in 3-5 seconds, they will ask a person or the web and ignore the static document--and often will not return to it
Users without core domain knowledge may struggle with basic core concepts
Documentation quality increases in measurable terms of completeness, consistency, clarity, and usability.
The domain model becomes the baseline reference for measuring quality and change management. When the model changes, the documentation must change to reflect it.
The documentation will describe what the user needs to do with the product and not just what the product does.
The documentation is more modular, with sections that can be targeted to different users, and reused across similar user groups.
With a systematic plan and process for covering the domain, managers get the best value for the time and resources allotted to documentation.
Different experts can write consistent and coherent parts of the documentation because the model defines how the parts fit together.
An explicit domain model is a valuable reference for validating assumptions and training new employees into the business space.
Domain modeling can and does reveal usability and workflow issues not just with the documentation, but with the user interface and the core product. A user-centric domain model can guide you toward aligning product features, user interface, documentation, and even sales.
With defined high-level requirements, your user knows what problem they're solving.
With defined actors, your user knows who they are and where they fit in.
With defined entities, your user knows what they're working with.
With defined use cases, your user knows what they're doing.
With defined workflows, your user knows what to do when.
With a clearly defined model as navigation, your user can jump the the right place and learn just what they need when they need it.
With the Rule of 3-7, a user can comprehend just enough detail at a glance. Just as there are 5 fingers on a hand, so 3-7 is one "handful" of ideas.