Sig A&D - Documentation And Communication

Learn, create and make it work

CIMSOLUTIONSAutomation for Industry & Business

SIG Architecture & Design

Documentation and Communication of a Software Architecture

David Meijers

February 5, 2009



[2]February 5, 2009 SIG A&D



[3]

Documentation – Introduction (1/2)

February 5, 2009 SIG A&D

Siemens Four ViewsRUP / Kruchten 4+1

Image: Lack of agility



[4]

Documentation – Introduction (2/2)

This is not about ADL’s

(such ACME, Rapide, Wright, Unicon)


System simple_cs = { Component client =

{ Port send-request; };Component server = { Port

receive-request; };Connector rpc = { Roels

{ caller, callee}}; Attachments { client.send-

request to rpc.caller; server.receive-request to

rpc.callee; } }



Designers(of interoperating systems)

Set of operations provided and required and the protocols for their operation (interface).

[5]

Stakeholders (1/2)


Requirements Engineers(customer representation)

Negotiating and making trade-offs among competing requirements.

Managers Basis for:1) forming development teams corresponding toIdentified work assignments, work breakdown structure, planning, allocation of project resources2) tracking of progress

Designers(of constituent parts)

Resolve resource contention.Establish performance and other kinds of run-time resource consumption budgets.



[6]

Stakeholders (2/2)


Architects Reasoning

Implementation teams Provide “marching orders”, inviolable constraints (plus exploitable freedoms) on downstream development activities.

Testers and integrators Correct black-box behaviour of pieces that must fit together.

Quality assurance team Basis for conformance checking (for assurance that implementations have in fact been faithful to architectural prescriptions).

Transfer Engineers (or Product line managers)

If and by how much a new product family member is out of scope.

Maintenance team Starting point for maintenance activities, revealing the effects of change.



[7]

Documentation guidelines

Write from the reader’s point of view, not the writer’s

Avoid unnecessary repetition

Avoid ambiguity

Use a standard format

Record rationale

Keep documentation current but not too current

Review documentation for fitness of purpose




[8]

The Carnegie Mellon approach (1/2)

Views and Styles

Viewtypes How the system is structured as a set of implementation units

(module viewtype) How the system is structured as a set of run-time interacting elements

(component-and-connector viewtype) How software structures correspond to system structures

(allocation viewtype)




[9]

Example: Module viewtype


UML notation:

Elements

Relations

Properties

(of elements and

relations)



[10]

The Carnegie Mellon approach (2/2)

Styles Patterns of design decisions. Module viewtype:

decomposition, layered, generalization Component-and-connector viewtype:

shared-data, communicating-processes, client-server, pipe-and-filter Allocation viewtype:

implementation, work assignment, deployment




[11]

Example: Implementation style


Informal notation:



[12]

Process

Create relevant views Document them Add documentation that applies to more than one view




So, what do we do specific for designers?


Software Architecture vs Design

What is Design?

What is Software Architecture?



[14]

What is design?

As a verb,

design is the activity of making such decisions.

...the resulting decision space may be large and complex.

As such, there is a science associated with design

(empirical analysis can point us to optimal regions or

exact points in this design space) as well as an art

(... degrees of freedom that range

beyond an empirical decision ...).


As a noun,

design is the named structure or behaviour of a system

whose presence resolves or contributes

to the resolution of one or more forces on that system.

A design thus represents one point in a potential decision space.

A design may be singular (representing a leaf decision) or it may be collective

(representing a set of other decisions).

Grady Booch



[15]

What is software architecture?

"Architecture" is a term that lots of people try to define,

with little agreement. There are two common elements:

One is the highest-level breakdown of a system

into its parts;

the other, decisions that are hard to change.

Martin Fowler


All architecture is designbut not all design is architecture.

Architecture represents the significant design decisionsthat shape a system,

where significant is measured by cost of change.Grady Booch



[16]

No project is the same

The role of an architect is highly contextual

But, the architect gets to define it

Pick the relevant views, the stakeholder will help




[17]

Communication – Introduction

Don’t you just hate it when an architecture is stuffed down your throat?

Does the architect ever talk to you?

Who is the architect anyway?




[18]

Communication – Basic Techniques

Become a friendlier person

Win people to your way of thinking

Change people’s attitude and behaviour (as a leader)




[19]

Become a friendlier person

Don’t criticize, condemn or complain. Give honest and sincere appreciation. Arouse in the other person an eager want. Become genuinely interested in other people. Smile. Remember that a person’s name is to that person the

sweetest and most important sound in any language. Be a good listener. Encourage others to talk about

themselves. Talk in terms of the other person’s interests. Make the other person feel important.




[20]

Win people to your way of thinking

The only way to get the best of an argument is to avoid it. Show respect for other’s opinions. Never say, “You’re wrong.” If you are wrong, admit it quickly and emphatically. Begin in a friendly way. Get the other person saying “yes, yes” immediately. Let the other person do a great deal of the talking. Let the other person feel that the idea is his or hers. Try to see things from someone else’s point of view. Be sympathetic with the other person’s ideas and desires. Appeal to the nobler motives. Dramatize your ideas. Throw down a challenge.




[21]

Change people’s attitude and behaviour

Begin with praise and honest appreciation. Call attention to people’s mistakes indirectly. Talk about your own mistakes before criticizing someone else. Ask questions instead of giving direct orders. Let the other person save face. Praise even the slightest improvement. Give the other person a fine reputation to live up to. Use encouragement. Make a fault seem easy to correct. Make the other person happy about doing the thing you

suggest.




[22]

Communication – Software Architecture specific?

Hints: Ivory tower

Start early (acceptance)

Don’t forget maintenance (don’t stop)




[23]

Conclusion

Documentation No documentation, no architecture

We have seen the process, but still haven’t learned the techniques

Communication Work on your communication skills.

Information needs to be selected and shared, not just published.





References (1/2) “Documenting Software Architectures

– Views and Beyond”, Paul Clements, et al

“How to win friends & influence people”, Dale Carnegie

Minutes of the Software Architect 2008 conference (3rd-5th June in London)




References (2/2)

“The Rational Unified Process – An introduction”, Philippe Kruchten

http://www.slideshare.net/DavidMeijers

IEEE Standard 1471

Date post:	18-May-2015
Category:	Technology
Upload:	david-meijers
View:	345 times
Download:	1 times

Sig A&D - Documentation And Communication

Technology