Get it in writing

I repeat this lecture ever so often.
Whenever possible "Get It in Writing" - not only to have proof of agreements but even more to make sure that both parties have the same understanding of them.
And sometimes it also provedes the means to make sure that you and the person you're talking with have the same understanding of implicit assumptions.
The most compelling story to back this was told to by a tour guide in New York when we drove along 42nd street.

When William Van Alen was hired to construct New York's Chrysler Building he was so sure of himself - the tour guide told us - and so well versed in the trades of the craft that he didn't bother to get a written contract. After all 5% of the buildings overall building cost was a well established fee in the market
After the building was completed - beating the Bank of Manhattan in the race for tallest building of the world - Chrysler refused to pay Van Alen with words like: "We don't have a contract. You should take more care to always get it in writing". Of course I don't know if this is a true story or not, but at least it serves well to remind me of my own advice.

OTOH it's hard to capture everything beforehand and some thing are so engrained into our perception of the world that I also tend to put more trust in the co-operation than I should.

Cheers
_MM_
(BTW: The story itself is of course backed - at least somehow, although with slightly different numbers - by wikipedia in the last paragraph about William Van Alen's Life)

scm & build: Levels of configuration

Hmm... nobody reminded me to send the next part... and I'm already 38 minutes late – nonetheless here's the first little part of the (to be) series on configuration management and build management.

Although I wanted to start with some clarification on "Task level commits" I actually concentraded on different levels of configuration in a build environment. Here we go...

The levels of configuration

One of the biggest differentiators between a one-man-show and a team-effort-project are the different levels of configuration that have to be managed – and this is also a point where the quality of whole build process can be influenced heavily.

Basically – unless the application to be is monolithic – there are four levels of abstraction: Machine dependent, user dependent, purpose dependent and (last but not least) project specific configurations. Each of this hast to be managed separately and consciously to avoid (to much) manual intervention. Talking about indirection let me cite (once again) David Wheeler to whom the phrase “Any problem in computer science can be solved with another layer of indirection. ” is attributed. As he stated in the second part – which is often omitted – “[But] this usually leads to another problem” so let's have a look at the relative pros and cons of this fine distinction. To start of lets examine each level a bit closer.

Remarks:

By the way: Of course there are at least two Dimensions involved in this topic as well: run-time configuration and build time configuration. For the sake of this argument I'll postpone this discussion towards the [[build]] topic.

Purpose dependent configuration

Let's start with the purpose dependent configuration since this is a concern covered in most modern environments. The purpose I'm talking about is also known as build type or target environment or something similar to that. Typical purposes are “Test”, “Debug”, “Release” or – a bit less frequent – “Integration”. Depending on the purpose of the build there usually are a number of things that differ. For “Test” there might be some hard-wired shortcut to circumvent server-roundtrips or a “don't really send to printer”-entry or some other special behaviour that is meant to make testing easier (or even possible) without imposing side-effects on already installed systems. If you're building for “Debug” – one of the most commonly differentiated purposes – you'll certainly want to include debug information into your code, something you probably don't want to ship (although that could be disputed, but that is another story). “Release” of course is the purpose with which you build the shippable product once all test and QA-work has been done. The necessity of an “Integration” purpose arises only in projects where you need to integrate several sub-products and usually has rather project-specific configuration needs.

And of course there are some things (e.g. logging) that need to be configured differently for each of these levels. But speaking of logging we encounter another type of configuration that should not be mixed with the purpose specific configuration: the project specific configuration of components. While I'll go deeper into those in the next paragraph, the important part with respect to things like logging is to be aware of the fact that some thing have both – a project specific configuration and a purpose specific one. Trying to manage both in the same way can create real nightmares (I guess, everybody who has tried to keep Log4J configuration files useful for an extended period of time without that conceptual distinction knows what I'm talking about)

Project specific configuration

This usually is the first configuration option you come across. Almost any project nowadays uses some reusable libraries. Those of course have to be adapted to the specific needs of the project and thus the first level of configuration indirection comes into existence.

Although these configurations are applicable on many levels – from configuration information specifying a windows' layout to the much mentioned log-file configurations – at least they have a clear association. They are “just another kind of source code” and thus relatively easy to handle.

Machine dependent configuration

This one strikes as soon as there is even one more developer! The path which used to point at /usr/bin has to point to /usr/local/bin, the drive for intermediates that used to be C: has to be E: and the monitor resolution goes from 1024x768 to 1600x1050. Consequently some things have to be configured somehow – and here we definitely need a distinction between build-time and run-time.

User dependent configuration

The distinction between user dependent configuration and machine dependent configuration is a bit hard to make in a time where the correlation of people:machine moved from n:1 to 1:n. But even now – where lot's of people have more than one computer the real relationship is more like n:m since some computers are still shared. Especially build and integration machines are prone to sharing. Now, even on the same machine, the configuration might differ in paths, desired screen resolutions and mounted network shares, so there is basically the same set of configuration information as there is in the machine dependent part, but it needs to be managed in a separate space.

To summarize: We have the purpose specific configuration which is a central [[build]] topic, the project dependent configuration that correlates to source code, the machine dependent configuration that correlates to hardware configuration management, and the user specific configuration that somehow correlates to profile information. All of these should have traceable connections to identify possible configuration errors.

After I have raised all these questions of course I should also answer them – I'll do so some time in the future and will provide a follow-up link in this post...

I think that even the concept to have different levels of configuration enables people to create more stable build environments.

Cheers
_MM_

Best Practices - like everybody does it?

In a recent Dilbert comic strip the much cited protagonist replies to his boss: "If everybody is doing it, Best Practices is the same thing as mediocre"

Made me think...


_MM_

Build-, Version-, Configuration- and Sourcecodemanagement,

Lately I found myself talking about buildmanagement and configuration management a lot. And since this blog lies deserted in the wild anyway I think this is the perfect place to ramble about that stuff so I can point other at some more ressources than I can right now. (And of course other can point me to my own ramblings if I get lost in the discussion)

Topics I’d like to discuss (although this probably wont ever come to an end) include simple, practical, down to earth things like

• The simplest way to set up svn to work with xcode for a small workgroup
  
• How to set up (any) DVCS for XCode
  
• How does SCM-integration work in XCode
  

but also things that seem to be intuitive to some but controversial to others

• Command line builds
  
• To branch or not to branch
  

and more conceptual topics (the most important to me) as

• Releases, Versions, Variants and other “Numbers”
  
• What is Multi-Dimensional SCM
  
• Staging and promoting 
  

Stay tuned for the first episode in about a week (and nudge me if I havent published it in two weeks!)

Cheers
_MM_

Strange ordering...

Strange - a few days ago I finally edited and released an entry from about a year ago - it still shows up in the old position. 

So - just to make it evident that I'm writing a little more again - I wrote this entry. The post in question was about the simple but disputable question "Are technical topics no business topics?"

Agile discussed by Jerry Weinberg

In an interview with PMBoulevard Gerald M. Weinberg states his opinion on agile Methods.

From that interview:

Q4: What is the future of Agile?
First we will drop the capital A. Then we will drop the term "agile" altogether. Agile methods will be successful if and when we stop seeing them as anything other than normal, sensible, professional methods of developing software.

That even someone as renowned in the field of "conventional" software development as Jerry Weinberg points to the common sense embodied in these methods makes me hope that someday the waterfall-style methods might vanish alltogether.
(via Jerry – of course)

Divas and Geniuses

In a blog entry from the start of the week Mark Masterson cited from the lessons learned document of a past project:

"Change the design / architecture to reduce reliance on the divas"

That reminds me of a former client of mine who used to say

"If you've got a genius in the team - get rid of him"

At first that's rather sad, but after a while - and with changing responsibilities - I came to realise that there can be situations (actually lots of them) where the advise is absolutely sensible.

It can be sensible because most developers are of average capabilities!
After all - that is exactly what average means.
Therefore the probability to have "above average" developers declines with the size of the project (and the organisation) simply because of the definition of average.
Even if all (or at least almost all) the developers in a certain team are "above average" (e.g. compared to some outside group of reference developers) most of them will - by definition - be of average skill within the team. That's where the "get rid of the genius" sets in.

If one of the persons on the team is way ahead of all the others - lets say she is a specialist in compiler construction - their advantage can become a disadvantage for the team as a whole. For those "geniuses" TSTTMPW (The Simplest Thing That Might Possibly Work) probably is quite different from the things the rest of the team perceives as "simple".

Configuration files are a good example - while plain text with very little syntax is the "simple" thing for most of us a specialist in compiler construction wouldn't mind using a sytax that is "syntactically a little richer" to gain simpler implementation. He might end up with a configuration language like sudoers' - where guides to the grammar (defined in EBNF) and the grammar's grammar are provided in the manual pages just to give the average user a chance to understand sodoers.


Actually I worked on a compiler project myself way back in the 80ies and used to be kind of fluent in BNF, but figuring out sudoers still took me a while. And judging by the amount of

<username> ALL=(ALL) ALL

(basically: allow <username> to do everything he wants as root)

that I've seen on other peoples Macs not many of them go to great depth deciphering the format...

Back to projects: Of course the idea to get rid of every smart person in the team would not be the best option - unless you want the project to fail.

But the "geniuses" - or, to be fair: those who have advanced knowledge and/or experience compared to the rest of the team - have to be handled carefully. Only for very isolated tasks they should be left to work it out all alone.

For the rest of their work they ought to work closely together with other team members as long as their personality allows them to adopt their ideas to a level thats appropriate for the whole team. Should the latter not be an option then option one is valid again of course - the team should get rid of 'em.

But in my experience that is seldom necessary Most geniuses are quite willing to agree on a sensible level of "simple" as long as their is a sensible discussion.

So after all it no so sad anymore. The bottom line of my job is not to get the "best" possible solution but to make the team as a whole as effective as possible

_MM_

Contracting Principles by Gerald Weinberg

I may not agree with everything he said, but the principles lined out by Jerry in his post on how to prevent consulting misery are a good starting point for everybody who is trying to figure out how to shape their relationships with their clients in a healthy way.

New Blog in Town

Since not all the things I want to talk about are really that relevant to an international audienc I just started another blog for the local topics.

...ups wrong link at first - sorry ...

From Cavedrawings to Hyroglyphs to Times New Roman - and back to Cavedrawings.

Sometimes I don't understand our business...
Just recently I listened to an interview with Grady Booch where he (once again) emphasized that he never intended the UML to be used for programming (i.e. as a programming language).
I‘m a proponent of visual modeling myself and after experiencing the method wars of the nineties I'm glad that such a thing as the UML unifies the meaning of arrowheads, boxes and dashed lines.
But I just can't understand why people think that they will be able to describe complete software systems of all kinds in pictures (although it's quite possible for some domains and to a certain level).
When thinking of the written word and picture I just can't avoid to think about cave drawings and "real" writing.
It‘s very common to judge the development of a civilization by it‘s capabilities to write. Or as Wikipedia puts it:

„Historians draw a distinction between prehistory and history, with history defined by the advent of writing. The cave paintings and petroglyphs of prehistoric peoples can be considered precursors of writing, but are not considered writing because they did not represent language directly.“

So where does it put our so called "industry" when some of us attemp to describe complex systems in pictures alone?

Talk: "methodological software development"

As I said - I'll try to keep this more current...

As mentioned in my previous post I just returned from my talk at the GI in cologne and besides the issues with the colour of my slides I think it went quite well.
I surely would attend the GI meetings more often if only they where not on tuesdays - the athmosphere was rather open and the discussions gave some rather interesting pointers.

For those who would like to see the slides again: You can download them from www.michaelmahlberg.de/GI-MethodenMichaelMahlberg.pdf. But you should be prepared for a somewhat lenghty download - apart from the "slightly" dark appearance on screen a textured backdrop tends to create large pdf outputs... in this case about 10 Megabyte...

Lessons from my last talk

As some of you may know im a big fan of Presentation Zen and try to follow some of the ideas in my talks. Today I was reminded of a few lessons I should have thought about beforehand:

No matter how cool your slides may look with that subtle gray-in-black backdrop and the translucent, intersecting areas - don't rely on it. Always keep a second set of slides handy that is optimized for bright ambient lights if you can't check the location beforehand! It's not important how it looks on your screen or in your controlled environment - it's import how it transports your message during the presentation. Therefore: bright coulours and high contrast for all unknown environments (at least as a backup).

Although I believe that a presentation is not the set of slide (i.e. you can never mail a presentation to someone - you can only mail the slides) I tend to put some effort in slide-design and so they ought to look good.

The other point is file size - since I converted to the Mac I tend to adopt a somewhat disrespectful attitude regarding the size of elements I use in a presentation - that's allright as long as the main point of the slides is to support the talk. As soon as I want to distribute them I could be running into trouble - for example when a simple 37-slide slideshow results in an almost 10MB pdf...

regarding the talk itself ... see next post

Upcoming Talk(s)

Following some examples from colleagues I'll try to post a little more information on my upcoming activities. Right now the list contains only one talk, but I'll try to keep the information on this blog more current in the future.

• I'll hold a talk on the state of the practice of "methodological software development" for the Cologne chapter of the GI (Gesellschaft für Informatik / German Chapter of the ACM ) on June 12.
  The talk will give a quick (20 minute) overview over practical experiences with applied development methodologies from SADT and IEM to XP and Scrum over the last two decades.
  Unfortunately the website is not quite up to date yet, but at least the location plan ought to be correct.
  

BTW:
Is "praxis-talk" really a legal english term?

Are technical topics no business topics?

I started to write this about a year ago - I think it's time to finish my earlier posts to get at least the basic ideas behind them in writing before I try to start new topics.

Every now and then I come across the silly notion, that technical decisions - like "Java Yes, Ruby No" - are considered to be "not of business relevance" and are to be left to the "IT department" since "the business folks wouldn't know anyway".

Apart from the inherent hubris from "IT" people with that attitude I think this point of view is rather short-sighted. If there are implications the business is not aware of it is the solution providers responsibility to inform the business people.

But - getting back to Java vs. Ruby style questions - to build a certain application with an estimated life-span of 6 month (e.g. because there is a legal requirement for exactly that time-span) might be a sensible thing to do in language 'Y' while it may be more sensible to assign two interns to do manual data corrections than to build an application using language 'X'.

You may substitute X and Y in the above paragraph with Ruby and Java respectivly according to your personal bias (or - for that matter - with any pair of programming languages) but the business people really should have a the last word in the decision.

ceterum censeo: We (including me) should really stop using the term "IT" ... if only I knew a suitable substitute ...

Dictatorship of the Dominant Decomposition

Well I thought this was well known, but obviously it isn't - a least outside the aspect-oriented crowd. So here are a few pointers for starters.

As a matter of fact I was wrong about the phrase though - it is called:

The tyranny of the dominant decomposition
(scroll down a little in the Glossary)

The original Papers can be found at ibm's reasearch site. Opposed to the AOSD glossary my preferred paper is the one about Multi-Dimensional Separation of Concerns. The one about Morphogenic Software is still worth a read though.