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.
)