xengineering

I have experienced great success with visual modeling based on the Unified Modeling Language. I am not going to define UML nor describe its origin in any detail – you can check UML in Wikipedia for that! – but instead focus on what I perceive to be its benefits and provide some useful techniques.

UML is an industry standard modeling notation – with that come some foundational benefits:

• You have the potential of handing your diagram to someone who already knows how to interpret the notation without being told.
• You can find books, training, articles, web sites, and other educational and support resources for UML.
• There has been widespread tool adoption of UML, from drawing tool templates to repository based modeling tools to integrated development environments.
• Many of your stakeholders can increase their market value by mastering the notation – don’t forget to tell them that!
• You can hire people who know how to read and write your diagrams without having to train them.

UML is also a very structured notation. That also brings benefits:

• The precise structure of the diagrams assists with consistency, completeness, and scope. Recasting your architectural vision into a predefined structure forces you to flesh out the appropriate details.
• The fact that it is a structured notation makes it possible for tool vendors to provide functionality to transform a diagram from one view to another or even to code.

Additionally, I think the UML notation itself carries benefits:

• While the notation allows for creative use of icons, in practice the notation is pretty generic. This actually speeds the diagramming process as more time can be focused on content and less on form. It also increases the readability of the diagram as the reader is not required to interpret symbols.
• There are different diagrams for different purposes. For UML novices – and even sometimes experts – this can be challenging. I sometimes find myself really struggling to add information to a diagram only to eventually realize that I am having a tough time because it doesn’t belong there! This “separation of concerns” means that each diagram can clearly communicate information without distractions. A picture that looks different from different angles is cool, a diagram that does the same thing is not!
• The core notation is very consistent. It is easy to learn and easy to use. The complexity to producing good UML artifacts is not understanding the notation, but determining the correct content. That having been said, the exercise of refining the content stimulates the design process in addition to producing clear artifacts.
• UML evolved out of industry best practices in diagramming and has evolved and been refined for 10+ years. There is always value in experience.

As I have gained proficiency in UML and embraced it as a powerful tool in my personal toolkit, I have identified some techniques that help me produce better artifacts:

• Use only the core notation. Finding some obscure facet of the notation doesn’t make you brilliant, but it does make your diagram less consumable.
• Label every diagram with the UML diagram type, your diagram purpose, and the last modification date.
• Fit your diagram on on standard letter size. Clearly, there are situations where it makes sense to break this rule, but this is a good rule of thumb that helps keep your artifacts with the right level of information to be easily consumable by your stakeholders. It also makes it easier to print and embed in documents. Some techniques to keep it page sized are:
  • Manage scope and detail and have more detailed diagrams with less scope roll up to a high level diagram with a broader scope but less detail.
  • Identify some categorization that lets you break the domain into multiple sub-domains.
  • Consider the purpose of the diagram and only put “fit to purpose” items on it. (see below)
• Only represent “fit to purpose” items on a diagram. One of the keys to “rightsized” diagramming is to only diagram what you need to be successful. If you are designing a solution in an Enterprise where every desktop contains Microsoft Word, you don’t need to include a component for Microsoft Word on the diagram unless the solution has some dependency or impact on it.
• Separate “concerns” onto separate diagrams. Some of this happens naturally due to the multiple diagrams available in UML. However, there are many things that can be depicted on each diagram type. Is the diagram for the hardware team? What is important to them? Certainly not the same things that are important to the code deployment team. This is a balance. You don’t want to have to maintain multiple similar artifacts, but, conversely, it is easy to over-populate a diagram with information and reduce its effectiveness. The information that is not of interest to the hardware team is nothing more than noise and distraction to them.
• If you are implementing diagramming standards for your organization – which I highly recommend you do – start with some clearly defined diagrams that are based on one of the UML diagram types, but provide users with guidance regarding the appropriate content and constrain which facets of the notation should be used. This will help people be successful with the contents of the diagrams, which is always more challenging than the notation itself.
• Scott Ambler’s Elements of UML Style is a fantastic primer of good technique.

I have truly found UML to be an extremely powerful tool and frequently use it to understand problems, design solutions, and broker stakeholder agreement! If you don’t already leverage it in your daily activities, you owe it to yourself to give it a try. It is an industry standard, so at the very least you can add it to your resume and increase your market value!

Bookmark It

Hide Sites

The American Heritage Dictionary (English Language, 4th Edition) defines artifact as “An object produced or shaped by human craft, especially a tool, weapon, or ornament of archaeological or historical interest.”

Interesting. In the software engineering field an artifact is (1) shaped by human craft; (2) in fact a very powerful tool, (3) can and will sometimes be used as a weapon, (4) has been known (given a decent plotter) to ornament many a cube, and (5) two years down the road it is certainly of historical interest. The Treasury Enterprise Architecture Framework (TEAF) provides a more precise definition of the software engineering use of the term – “An
abstract representation of some aspect of an existing or to-be-built system, component, or view. Examples of individual artifacts are a graphical model, structured model, tabular data, and structured or unstructured narrative. Individual artifacts may be aggregated.”

To the lay person, an artifact is simply a document.

I was once assigned by a client to provide architecture guidance to a project that was well under way in order to minimize the damage. I seem to frequently have the pleasure of engaging with a project much like a person on a bike engages with a bullet train – I try my best to catch up, but I certainly have to pedal fast. (Incidentally, architectural legs do pedal faster with conditioning.) Anyway, I knew there was a problem when the conversation started like
this:

Me: Hello, I am really exited to come on board. < insert really smooth introduction to the value of architecture here >… so if you send over whatever requirements documents you have, I can ramp up and ensure that the technology solution aligns with your business needs.

Stakeholder: I don’t have a requirements document.

Me: < insert stunned silence here > But you have a signed time and materials contract with the vendor. How are you going to ensure you get what you want?

Stakeholder:I know what I want and I explained it to them. (Instantly demoted from “stakeholder” to “person on phone”)

True story. It might be a story without a train wreck ending if the project team was small or the problem space was well understood, but neither was the case. Fortunately, the client eventually saw the risk, stopped the train, and found a new conductor.

You might be able to get by without requirement and design artifacts if you are designing for yourself and are your own stakeholder or if the number of stakeholders is extremely small and highly engaged in your design process. Even in those situations, your project would benefit from artifacts. In my experience there are very few projects where the problem and the solution cannot be better understood with some level of artifacts.

It can often be a challenge the first time you introduce the concept of capturing and using artifacts – particularly where people aren’t in the habit of producing or using them. You may find yourself wondering where to start. To help you hit the ground running, here are some of the techniques I use most often:

• Enable a shared vision. I have found that in a conversation with five people, each leaves with different threads resonating. Working as a team on a central artifact – a diagram, a list, a use case, whatever – is an extremely effective way of brokering clarity across a project team. In the decentralized model, everybody takes personal notes with personal interpretations of the discussion. In some cases, perhaps a project manager or analyst scribes the entire meeting as “meeting notes”. Both are better
  suited for defense than success. Since there is not a shared “in scope” artifact, everybody will be marching toward personal notes which will be pulled out for defense when something goes wrong, but do not contribute to a shared vision. Scribed meeting notes likewise get filed for defensive use in the end game. Ask people to bring nothing but their thinking caps to your requirements or design meetings. Then, use the whiteboard or a sticky wall (see this article by Ellen Gottesdiener) to capture a shared artifact. Put that useless digital camera phone to use and email out the results – Poof! Instant artifact!
• Encourage feedback (“The Straw Man”). Producing a draft artifact for review prior to a requirement or design session will always stimulate discussion. Even, drafting an artifact that incorrectly identifies information will serve as a catalyst for feedback, since people are quick to identify mistakes. Remember – that was the plan. Don’t get defensive, just capture the information you needed!
• Guide discovery. I am a big proponent of formal artifact techniques. Standard notations (like UML) and approaches (Cockburn-style Use Cases) provide a structure that guide both scope and completeness. Creating the artifacts basically acts as a questionnaire that forces you to ask the right questions in order to complete the artifact. The
  very act of producing the artifact helps you understand the problem or solution in a way that would have eluded you otherwise.
• Define scope. Clearly identify which artifacts are in scope and which are not. If information is not part of an in-scope artifact, it doesn’t count. Sounds a bit totalitarian, but it trains people to contribute to the well being of the in scope artifacts and minimizes the likelihood of some critical piece of information being lost in a deluge of emails.
• Leverage visual models. I am a huge proponent of visual models, specifically UML-centric visual modeling.

Requirement and design artifacts are extremely powerful tools and should not be underestimated!

I would also like to debunk some common “artifact” misunderstandings:

• “We don’t have time to produce those documents.” Typically, the time-consuming part of producing well-designed artifacts is figuring out the content, not the act of completing the artifact itself. If this is what you think, you should actually be saying “We don’t have time to figure out what we need” or “We don’t want to think about the design now, we want the problems to sneak up on us later.” Artifacts are actually tools used to understand the problem, design an appropriate solution, and ensure clarity
  among stakeholders. The power of artifacts is in the trip as much as the destination.
• “Hey, do you know how to type? Good, you can do the documentation for us.” While it is unbelievably common to believe that anyone who has free time and a word processor can produce effective artifacts, that is most definitely not the case. It is the equivalent of saying that anyone who can use a paintbrush, can paint a Picasso. I can, in fact, use a paintbrush, but I’m challenged to paint a wall. The ability to capture information in a well scoped and clear manner is a skill which is not to be confused
  with ability to use Microsoft Word. In addition, producing artifacts cannot be a sidelined activity performed by a spectator – this is not news reporting!

In closing, while I concur that heavyweight documentation is definitely not needed (or helpful), the logical foil is not “no documentation”. The answer is that the right number and type of artifacts should be produced in order to reduce risk and ensure the success of your endeavors. What is needed is not heavyweight nor lightweight documentation, but rightweight documentation! Determining the right number and type of artifacts is left as an exercise to the reader.

Bookmark It

Hide Sites