Controlling and Documenting Software Development: a new approach

I’ve been reading a Tom de Marco’s article these days, where he reconsiders the “You can’t control what you can’t measure.” phrase.

http://www2.computer.org/cms/Computer.org/ComputingNow/homepage/2009/0709/rW_SO_Viewpoints.pdf

“I’m suggesting that first we need to select projects where precise control won’t matter so much. Then we need to reduce our expectations for exactly how much we’re going to be able to control them, no matter how assiduously we apply ourselves to control.”

Another great piece is the 1997 Bertrand Meyer’s satiric article. It is undoubted joking but most of it fits real and up to date for me.

http://archive.eiffel.com/doc/manuals/technology/bmarticles/uml/page.html

“In its attempt to show that it has included everyone's pet ideas, it is a chock-full of symbol after bizarre symbol. Just the "Notation Summary" takes up 60 pages and has its own table of contents! UML is in fact as complex as a big and cryptic programming language, with generous use of "$" and "#" and "-" and "*" and "solid triangles with no tail" and rectangles and diamonds and solid lines and dotted lines and solid ellipses and dotted ellipses and arrows of all kinds and keywords such as "const" and "sorted" (not to be confused with "ordered") and different semantics for a class depending on whether its name appears in roman or italics; but at least a programming language, even the worst of languages, is executable! Here you have to learn all this monstrous complexity just to build diagrams of a possible future system.”

“For example I have tried to see if I could characterize UML as "object-oriented"; we all know this is a great compliment. Fat chance. Of course the authors make the requisite use of "object" and "inheritance" and so on. But a mere glance at the diagrams shows UML for what it is: an extension of entity-relationship modeling. The basic examples show binary and ternary associations, such as (page 16 of [1]) associations between "flight" and "seat" and "person"; this is the exact opposite of object-oriented design, where, as we all know, the world is structured in classes, built around object types, and every operation or property belongs to one class. Surely in object-oriented design you can't have a "passenger" link that treats "seat", "flight" and "person" symmetrically! In an object-oriented system it would belong to one of the classes; that's how you obtain the consistency, simplicity, modularity and reusability of O-O architectures; look at BON or at Eiffel to enjoy the results. The authors of UML know this, of course; to understand why they call UML object-oriented we must appreciate their famous sense of humor. Obviously they meant it in jest.”

“How could I criticize the method for not helping software developers or managers, when it does not care about software development at all, but only about developing a market for consultants and trainers? Everything started to make sense: the complexity and bizarreness of the notation, which I had foolishly taken for a deficiency, are in fact among its most attractive qualities, since they make for endless business opportunities, for Rational and perhaps even for others as well; so does its lukewarm adoption of object-oriented ideas, since it means a consultant does not even have to like or understand object technology to profit from UML.”

My growing interest on agile philosophy and methodologies, trying to convince my job mates (all levels), to give the software project control and documentation a much more soft touch, the Design By Contract approach sounds much more smart and agile to me now.

I like so much this practical approaching article:

http://devlicio.us/blogs/billy_mccafferty/archive/2006/09/22/design_2d00_by_2d00_contract_3a00_-a-practical-introduction.aspx

So, in the control and document software development subject, we have:

The don’ts (old fashion):

• Instead of hard control software development, try to deliver software that makes a difference.
• Function Points is not an effort estimation method; don’t try to estimate time spent using it.
• If the average managers try to deliver software on a seni
• or developer time line with a bunch of junior or even trainee developer team, why in the Earth do we need to over control software development? And worst, why to use FPA to measure it.
• Since UML is not simple, agile, or even OO, why in the Earth do we need to use UML when modeling or documenting software development?

The Do’s (new fashion):

• Manage the people and control the time and money.
• If you want to control something in software development, control its quality.
• Use Mind Mapping to barely document the software requirements (user stories).
• Use DbC to design the software.
• Use a smart and agile (like Rails) technology to implement it.
• Use XP methodologies when implementing it.
• Applying BDD, use executable specification and documentation techniques.
• If there is an obligation on measurements and control, use an agile technique like “AgileEVM” for instance.

And remember: what really matters to the customer is:

“BUSINESS VALUE DELIVERED PER SPRINT”

So, that is exactly what we need to focus on.

Applying agile methodology is a waste of time

People some times wake up “Agile” no mater what.

After a few years, working on the customer site, things change a bit, and now we are working for the same client under a new OUT sourcing contract, so, I came back to the “home” office.

The first thing I have noticed back to the office was the “java team agile style”.

There is a task board on the wall;
The Java source code is under CVS control using “sprint” branches;
They have regular meetings every week…

So I need to ask my VB team mates: You are not agile yet? Why? Does your working environment let you be or become agile?

A few weeks later I realized that the point is not agile methodology but agile PHYLOSOPHY.

If your working environment doesn’t embrace the agile philosophy, there is no way to become agile no mater the amount of agile methodologies you use.

Some practical examples:

The weekly meetings were not focused on the project sprint deliveries, and soon they were disabled for the “big project” the java team was working on. And the other projects are not “big enough” to be selected by this kind of weekly meeting.

I need to implement an urgent but simple feature on the original java application they were working on (the big project). So I asked on which CVS “sprint” branch I should work and was told to use the 5th sprint.

Then I asked when the user have received this sprint, and was informed “No there is no sprint delivery to the client, we are working hard the last 6 (six) months implementing the new functionality and trying to integrate it with the original application”.

Well that is my point, why do they waste their time applying some agile methodologies if the overall philosophy remains waterfall.

This brings me back to the source “The Lean Principles”.

• Specify value from the standpoint of the end customer by product family.
• Identify all the steps in the value stream for each product family, eliminating every step and every action and every practice that does not create value.
• Make the remaining value-creating steps occur in a tight and integrated sequence so the product will flow smoothly toward the customer.
• As flow is introduced, let customers pull value from the next upstream activity.
• As these steps lead to greater transparency, enabling managers and teams to eliminate further waste, pursue perfection through continuous improvement.

If we can put it on just one phrase, the “Lean Philosophy” is:

Do nothing but what gives to your customer some value.

So which is the value to the client on using the precious development time specifying and modeling the full feature; calculating Function Points for it, creating a document detailing each aspect of it, and implementing each of the possible functionality, with no delivering at all.

At the end we can see: if the enterprise still waterfall there is no way to be agile.

First of all we need the enterprises to become agile; we need the managers on both sides to become agile.

There is no way you could be agile if your manager insists on detailed upfront schedules.

There is no way to be agile if your manager insists on FPA for each functionality.

There is no way to be agile if your customer demands a huge amount of documentation.

There is no way to be agile if your customer demands a lot of form to be filled out just to get a new version of the application deployed.

So, managers, please read a few books about being agile, starting here.

And you folks, developers and other professionals try to share the agile philosophy before the agile methodology.

If you try to use agile methodologies into a “waterfall” environment, you are wasting your time a bit.

Good luck.

Cloning GitHub Access

Here is another very basic guide into GitHub usage.

After you have used GitHub for a while, you will have a desire to spread that usage over all your machines.

You would like to clone from GitHub from your notebook, from your machine at work…

To get this, you have two options:

Create an SSH key on each of those machines, and add then to your GitHub account.

Or you can replicate your single current SSH key on all of those machines.

To achieve that, all you need to do (In Windows), is to copy these files / folder from your original GitHub access machine home path to the others.

C:\Documents and Settings\Ricardo>
C:.
│   sshkey.txt.pub
│   sshkey.txt
│
└───.ssh
    id_rsa
    id_rsa.pub
    known_hosts

That is it.

I would like to ask you all from Linux and OS/X, to comment here how to do the same on these environments.

github primer: the real one

All the articles I have read about getting started on github are not so “primer”.

Take for instance, my favorite article on getting started with github:

Getting Started with Git and GitHub on Windows.

It does a great job, until the “Set up your GitHub account” picture.

After that it turns specific, and supposes the readers will fork his project…

Others, starts the action by cloning an empty repository, which makes no sense.

This primer, is supposed to be your very first incursion into github, so, I will not give you the entire alphabet, just the “A” letter.

I’m supposing you have already installed your git client and done with your github account, now what?



Everything is empty on my github account. What can I do next?

First you need to create a new Repository:

You just need to fill out this form:


With at least the Project name which will become the Repository name.

Or (that was my case), just rename an unused one with the desired name:


This will let you with something like this:


With your own “Clone URL”, that will be used on the next steps.

Now let’s go and create some content and push it into this new Repository:

Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.

E:\GitHub>md mynewgithub

E:\GitHub>cd mynewgithub

E:\GitHub\mynewgithub>git status
fatal: Not a git repository

E:\GitHub\mynewgithub>git init
Initialized empty Git repository in E:/DreamHost/GitHub/mynewgithub/.git/

E:\GitHub\mynewgithub>git status
# On branch master
#
# Initial commit
#
nothing to commit (create/copy files and use "git add" to track)

E:\GitHub\mynewgithub>notepad readme.textile

E:\GitHub\mynewgithub>dir
Volume in drive E is Dados
Volume Serial Number is 5C89-E09F

Directory of E:\GitHub\mynewgithub

01/01/2009  04:38 PM    <DIR>          .
01/01/2009  04:38 PM    <DIR>          ..
01/01/2009  04:37 PM    <DIR>          .git
01/01/2009  04:39 PM                77 readme.textile
             1 File(s)             77 bytes
             3 Dir(s)   5,366,173,696 bytes free

E:\GitHub\mynewgithub>git add .

E:\GitHub\mynewgithub>git status
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#       new file: readme.textile
#

E:\GitHub\mynewgithub>git commit -a -m "My first commit on github ever"
Created initial commit f213d62: My first commit on github ever
1 files changed, 3 insertions(+), 0 deletions(-)
create mode 100644 readme.textile

E:\GitHub\mynewgithub>git branch
* master

E:\GitHub\mynewgithub>git status
# On branch master
nothing to commit (working directory clean)

E:\GitHub\mynewgithub>git push -f git@github.com:marcric/mynewgithub.git master
Counting objects: 3, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 291 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@github.com:marcric/mynewgithub.git
+ 2fdc3ed...f213d62 master -> master (forced update)

E:\GitHub\mynewgithub>

And then, supposing this is the “readme.textile” file content:

h1. That is my first github project

h2. And this is my first README file

You will have something like this:


Now it is OK to start forking, cloning, merging and what ever you want to do with git on github.