Today I have learned about Ishikawa diagram (AKA fishbone diagrams, herringbone diagrams, cause-and-effect diagrams, or Fishikawa). And I started to wonder whether it makes sense to use it to diagnose the issues related to the production of software. (I will not explain Ishikawa diagram in this post, so please have a look at Wikipedia description if it does not ring any bells for you).

I wanted to try it myself, so I choose an arbitrary (but quite common) problem – “low quality of software” – and tried to use Ishikawa diagram to find the causes.

I have to say that I’ve enjoyed this little experiment. At first I thought that I will have to modify the original categories, but after a while it occurred to me, that no major changes, but rather a refactoring of names is required (the descriptions were copied from Wikipedia article):

  • People Anyone involved with the process – no need to change, there are many people-related problems in IT.
  • Methods: How the process is performed and the specific requirements for doing it, such as policies, procedures, rules, regulations and laws – I think the “Process” term is better suited for software development.
  • Machines: Any equipment, computers, tools, etc. required to accomplish the job– I would suggest to use the “Tools” term which includes both the hardware (devs machines, CI server) and software (i.e. IDE)
  • Environment: The conditions, such as location, time, temperature, and culture in which the process operates – maybe not so important in case of software development than in factories, but also worth analyzing. No name change here.
  • Materials: Raw materials, parts, pens, paper, etc. used to produce the final product – this made me think for few seconds. Then I realized that the material we work is, is simply the software. I have left the “Materials” term unchanged, but other names (e.g. Application or System) would be also fine.
  • Measurements: Data generated from the process that are used to evaluate its quality – hmmm…, I think that would be various metrics like code coverage etc.

So the starting point is this:

2013_11_ishikawa_categories

(HINT: click to enlarge)

I spent like 10 minutes drawing a diagram for a hypothetical team (definitely NOT the one I currently work with!). And this is the result.

DISCLAIMER: I do not claim this diagram to be complete, or very smart, or that it solves any real issue. This was only my attempt to see how this tool – Ishikawa diagram – could be used. Got it?

BTW. I have used XMind (free version) to prepare the diagrams. In reality that would be probably pen & paper (a very large paper!).

Here is an “overview” (with only first-level causes visible):

2013_12_ishikawa_first_level

The beauty of electronic version is that you can hide some parts of the picture and analyze a selected branch or two. Below an example example of single category analysis in all its glory:

2013_11_ishikawa_one_branch

As you can see you go as deep as it is required to find the causes which cause other causes 🙂 “5 whys” is the technique you would probably use for this.

The whole picture could look like this (it doesn’t matter that you can’t read the small fonts, really):

2013_11_ishikawa_all

Now the team could look at all the issues described and decide which of them are of the main importance (“root causes”) and should be fixed.

Yes, I like it

Ok, to conclude, I would say that I like the idea of using Ishikawa diagram for finding the major problems of software development. I could imagine a team working with this diagram.
The fact that you have 6 different categories there would make team consider a vast range of factors, which could result in finding not-so-obvious stuff. Having so many perspectives makes it harder to stop right after finding the first possible cause (e.g. someone says “it is all because testers are lazy!” and the rest agrees and the discussion is over).

So now it looks like I’m now in a “solution-looking-for-a-problem” situation. I have this nice tool (Ishikawa diagram), I have an idea what problem could be solved with it (finding most important issues for team in troubles), but I have no team that would need such analysis. 😉

And what about you?

…and maybe you have used this diagram (or a different one?) to find/solve some issues within your team? I would be happy to learn about it!
Or maybe you have your ideas about when/how to use it? Do not be shy, share them with the world! 🙂

Source file – xmind

You can download the original xmind file here.

Code reviews. Very helpful if done right, completely useless if done recklessly.

Below you will find a mindmap of “code review” (using Xmind). I simply sat down and tried to gather everything related to code reviews. Hopefully you will find some food for thought here.

2012_code_reviews

Some comments:

  • I knew one team lead (hello Marcin! 🙂 who had a very nice system of publishing code reviews by email to project’s mailing list. He believed (and had some good results to support this belief) that by doing such “public” code reviews he educates the whole team, and not only the author of the particular code. It worked for him and his team pretty well!
  • Marking code with TODO and FIXME during the review works pretty well for me. Nope, I haven’t used gerrit or any other tool like this yet.
  • IMHO code review should be a part of Definition of Done – no task is finished until someone else checked the code.
  • I don’t like the idea of team lead doing code reviews for the whole team. He has probably no time for this. The other thing is that some people find it hard to discuss with your “boss” (so they will follow blindly what the reviewer says). I like much more the idea of peer reviews. Even if some junior guys are not capable of performing code reviews properly (at least from the very beginning).
  • There is a great discussion regarding code reviews here.

So I’m taking over a new project as a technical team lead. This team has been working for some time (for a long time). Now my task is to lead its further development. I’m excited and worried at the same time.

I spent some time wondering about what should I know about this new project and about the team. Here is the list of topics that I think I should gather some information about. Maybe someone else will find them useful. I also hope for someone giving me hints about things that I forgot.

I did not mention some obvious stuff like “what the project is all about”. The list is chaotic, but so am I. 🙂

Team

  • who? + characteristics + how long they work with the team + strong/weak points + maturity level / how independent they are? + maybe there is some BSC mechanism, if so, take a look at the previous records
  • language skills
  • contact – mail, skype/jabber nick etc.
  • working hours? anyone working half-time? anyone with unusual working hours?
  • where? one room or many places
  • some people from other teams involved? independent consultants? some project partners (external companies) that we cooperate with?
  • what are the roles of people
  • who knows what?
  • are team members involved in other projects?
  • questions to ask to each team member:
    • what are you proud/angry/annoyed about? what (de)motivates you?
    • please draw the architecture of the system
    • please write down the “definition of done”
    • what issues do you think we have? what is the most common source of bugs? which bugs are the most annoying for us / for clients?

Meetings / Telcos

  • internal (only the team is involved) – Scrum – daily / sprint / backlog ?
  • with clients
  • with higher-ups?
  • traveling? where? for how long?
  • how are the invitations send? who sends them? who sets the agenda? who sends minutes (if any)? who attends?
  • how long is the meeting? who participates?

Documents

  • where can I find them, how are they generated, who maintains them?
  • technical documentation
  • user documentation
  • developers documentation
  • reporting – internal / external
  • templates – documents? mails? reports? presentations?
  • bug tracker – how are issues commented?
  • where is the database schema?

Infrastructure

  • SCM, FTP/WebDavs, Sonar, CI, bug tracker, artifacts repository, wiki
  • keystores, certificates
  • mailing lists (internal, external)
  • adresses, credentials, who creates accounts? who administrates?
  • environments – local, testing, production?
  • Can anyone, besides the team, access any of these (e.g. client reading bug tracker issues) ?

Processes

  • SCRUM? how does it really look like? how are user stories sized – hours or t-shirts (M, S, XL)? what meetings, how often etc., are daily standups held regularly
  • code reviews – formalized, informal, who does them? peer reviews? external audits of code?
  • any visualization tools? (well, these are the easiest to notice, aren’t they?)
  • what is the “definition of done” of this team?
  • any special recruiting process for this team?
  • build process – automated?
  • How are versions/releases created? What is a naming pattern? Are there different internal (for team) and external (for client) versions? How can one learn about the changes between versions X and Y?
  • statuses of issues on issue tracker (e.g. todo, in progree, done, accepted etc.)
  • production deploy & rollback, tools used – Puppet, Liquidbase?
  • code conventions – format (Eclipse formatter?), checkstyle etc, but also use of TODO/FIXME tags in code
  • SCM (SVN/git) – branches? how/when created, when merged?
  • CI – schedules, how are they set?

Testing

  • unit
  • integration
  • end2end
  • does client test?
  • automation? which requirements functional and non functional are being automatically tested?
  • code coverage – how high, is it automatically calculated, is code coverage of different tests merged?

Development Tools

  • what tools/software is being used by team members
  • OS? IDE? build tools? testing libraries? mocking libraries? code review tools?
  • specific applications for Win (Visio?, Outlook?)

Problems

  • what we know? what are the main problems from our point of view? (e.g. internal code quality, our build process, client?), does client is aware of this?
  • recent problems, what were the causes, are they fixed?
  • what is the main concern of client?
  • common bugs, how many critical bugs, are they added to the current sprint?

Client(s)

  • communication – how do we communicate with clients? with whom exactly should I talk about certain topics? who has the right to make decisions?
  • communication – how does client communicates with us?
  • communication – what hours is he available? does he answer emails immediately?
  • what does he value, what are his goals?
  • does he own the code?
  • does he has a say in technologies we used, should we ask him for approval for new libraries/tools that we plan to use?
  • is it possible to negotiate the scope?

Next steps

  • What is the most pressing matter? Are we late with anything?
  • Any meetings/telcos ahead?

Architecture

  • software
  • hardware

question-marks_0
Questions, questions, questions… Surely there are many more things to ask and topics to understand when you join a project. I will try to use the above list for the task at hand. Will see if it turns out to be any good.

The progress of computers and software has taught us, that there are not many things that can not be done. Linux, Google, Facebook, cloud computing, open source etc. has shocked us with solutions we hadn’t even dreamed about. Still, I often hear (and use myself) this phrase: “it can’t be done”. This post is about trying to understand what is really hidden behind these words.

Source: http://eaonpritchard.blogspot.com/
Peter Ustinov

No Time

Sometimes this simply means, that I don’t have time for this. Sometimes I don’t even have time to think if it is a good idea. I have so little time, that I don’t really care if it can or can not be done. I just don’t care. All I care about is to kill this idea before you get excited and make me ponder it over. So I say “it can’t be done” hoping that you’ll take this excuse for real, forget about it, and I will not be burdened with another task (because I really don’t have time, got it?).

Incompetence

I know nothing about this, and I feel incompetent. But because I’m afraid or ashamed to acknowledge it, I will tell you that “it can’t be done” in order to:

  • make you think that I know the subject,
  • convince you that there is no point in even trying.

We Really Can’t Do It

I know a lot about this, and I know, that if we were to discuss the details, we would end up with a conclusion, that this is too costly or that we more important things to do. Whatever the reason, I’m 100% sure, that we would end up deciding not to do it. So to spare us both the troubles of discussing it, I tell you that “it can’t be done”.

Not On My ToDo List

I know it can be done, but I have other more pressing (or interesting) things on my mind, or I am too lazy to do it. So I will tell you that “it can’t be done”, in hope that you get off.

Never Ever Before

If I tell you that “it can’t be done”, then I can simply mean, that we have never done it like that before. It also means I’m afraid to try. I’m afraid, because we may fail, and I don’t like failing at all. But I’m also afraid that it might work out pretty well. And then we would discover that we were doing things wrong (or suboptimal) all the time, that the new way is better, faster, easier, cheaper.
As you can see, it is simply safer to say that it can’t be done…

What Is Your Excuse?

Now, every time someone tells me, that “it can’t be done” I wonder which one of the above does he mean…

Sometimes if you look closer at projects names you will notice some interesting stuff. This short post is exactly about this – names of projects that are more than mere identifiers.

Let us start with an obvious example of C++. The name indicates that C++ is a successor (a better version perhaps) of C (++ being a increment operator in C).

Similarly Ruby language is a successor of Perl (also a jewel) yet the etymology of the name is more complicated (check Wikipedia’s entry on Ruby).

The name of popular Java IDE – Eclipse – is also significant if you think about IBM (original founder of Eclipse project) as a rival of Sun Microsystems.

Things get really interesting when we dive into the area of testing. A bit of history first. Once upon a time there was a company called Mercury (full name: Mercury Interactive Corporation). This company produced testing software. Now, Mercury is also a chemical element (Hg) which is poisonous. Another chemical element – Selenium (Se) – is believed to have protective effect against Mercury. And Tellurium (Te) – yet another chemical element – is chemically related to Selenium.
So, we have three testing tools – one produced by Mercury company, one called Selenium and one called Tellurium. Pure coincidence, of course. 🙂

Also in the testing world we have a great Mockito framework. Even thought its name really comes from mojito drink, its name resembles also moskito. This is probably why another mocking framework is called Komarro (komar is how we call moskitos in Poland).

Similarly, Iceweasel is a fork of Firefox.

Thanks God, project names can also symbolize friendship. Take a look at Hansel and Gretel projects. These two coverage tools share some amount of source code and names derived from a popular German fairy tale.

I also like very much the Reactor project accompanied by it’s Clojure interface called Meltdown. 🙂

Help!

Do you know more examples of such interesting names? Share them with me, please!

So you are a geek? And you want to present a technical topic on JUG or maybe some conference? Ok, here comes some anti-patterns that will help you to ruin your talk. 🙂

The anti-patterns presented here were gathered during many JUGs and conferences that I attended over a span of few years.
Because I see them occurring here and there, I decided to publish my thoughts. Hopefully you will find them useful.

Run before they ask!

I have seen this one so very often! It goes like this. A speaker ends his talk and switches the last slide with “Q&A” written with big letters. He says quickly “any questions?”, scans the audience, says “no question? So thank you blah blah blah” and dashes off as though he was being chased 😉
Now this is ridiculous. If you act like this you will never get any questions. You need to wait around 15 seconds after you asked for questions before some people will dare to say something.
So, start counting it in your head. Slowly.

1,
2,
3, slowly, don’t rush,
4,
5,
6,
7,
8,
9, be patient they will ask
10,
11, AH, HERE IS THE FIRST ONE!

People are shy, people feel uncomfortable when they are to speak in public, they need time. Make it easier for them. Show them that you really await their questions. And if your talk had any sense someone surely will ask.

Of course, sometimes the audience does not need time nor encouragement and will ask immediately or even interrupt you with some urgent questions. Good for you!

And one more thing. Q&A session is very important and it looks really pathetic if you try to avoid it. Your talk was fully controlled by you, which means you could omit some weak points. During the Q&A part you will have to face your fears, because they will ask about real problems and probably will touch stuff that you wouldn’t like to discuss at all. This is the moment that you can gain a lot or loose a lot. But running away is not an option.

Have a private chat with first row people

A guy in the first row asks a question. you are so proud that you know the answer that you reply to him right away.
WRONG! The rest of the audience has no clue what the question was because they simply did not hear it. The guy in the first row spoke quietly so only first three rows had a chance to understand him.
Remember, you should always repeat (paraphrase) the question aloud. It will make all the people hear it so they can benefit from the discussion that will follow.
Also remember to reply loud enough so the whole audience can hear you. You are not replaying to this one person who asked – they all want to hear the response.

Talk about your mistakes

Oh, so you made a mistake. Maybe you switched slides too quickly and now you would like to go back, or maybe you forgot to show them one example, or whatever. How terrible! Now you feel that you have to tell about it, that you have to explain what you should have done, what you did, why you did it and so on.
Remember you are the only one that knew what was planned and that it didn’t go as expected (unless you show it with your face). The best thing you can do is to pretend that everything is in order

Instead of apologizing and explaining (“oh, I forgot to show you X because blah blah but now I will blah blah”) simply say “there is one more thing that I would like to show you” or “let’s go back to the previous example and discuss X and Y”. It is much better than to elaborate on your feelings.

Tell about the things you won’t do

(This anti-pattern is very similar to the previously described one.)
So for some reason you are not able to show everything you have planned. Maybe the net was down or you have less time than you prepared for or for whatever other reason. The bad thing to do is to talk about this. For some unknown reason you feel you need to explain it, to tell them what was planned and what they won’t see because of A and B and C and …. What is the result of this? Well, the audience will feel as they were robbed from the best parts of your show.
Even if this is true you should not concentrate on this. Simply go on with what you can do and what you can show. If you feel that this “missing part” is so very important then you should think about the way that you can deliver it to them on some later time. Something like “because it is an interesting aspect I will prepare and online demonstration of this feature” or something. But cut it short, don’t make them feel that they missed the best part!

Talk about yourself

Sure, they all came here to listen about your great achievements. Put at least 3 slides about yourself, your company and your hobbies. They will surely love it. 😉

Make it hard to read or boring

Some anti-patterns related to visual aspects of your presentation.

Put everything on a slide and read it

Yeah, your audience can’t read.

Make it hard to read

Some often seen anti-patterns.

  • put things on the very borders of your slides – some projectors will nicely cut off the borders,
  • use the default font setting for your command line and IDE,
  • use not very contrast color which look very nice on your LCD,
  • spent first 10 minutes configuring your desktop so it works with the overhead projector.

Ok, now for real. You should set font size before you start or at least you need to make sure that you know how to do it. For a command line it happens that white background and black fonts are better visible with overhead projector.
The best thing you can do is to present an example of command line and IDE screen before you begin your talk and ask the audience if it is readable.

As for colors they will look different on the wall than on your LCD. Use black, white, read and avoid very thin lines.

And if possible you should try your desktop settings long before your talk starts. It saved me once at Geecon 2009 – I plugged in ~3 hours before my talk and it didn’t work. Thanks God I had so much time to fix it!

P.S. If you spend some time browsing the internet you can find some valuable resources, like this one.

When can you say that a task is done? This is an old topic but still important and still being discussed over and over by almost any team. Lately my team decided to come with a definition of done. This post presents our view on “what is ‘done’?”.

Introduction

We tried to address every aspect of development – from coding & testing to documentation.
BTW. the order of things on our cheat sheet does not determine the order of work. For example TDD is more than welcomed so it is not like tests come after the code. Similarly javadocs don’t have to wait for the finishing of code activities.
The important thing is that our cheat sheet groups all things that should be done in one place.

Another issue is to realize that you will never be able put every detail on such cheat sheet. If you want it to be readable you need to choose words carefully. The point is, that everyone should follow the spirit of the law more than the letter of the law. If there is a point on “code quality check with Findbugs/PMD” it is rather obvious that you should use Codenarc instead, if you code Groovy. It is also obvious that often only some of these points are relevant for certain tasks (e.g. if your task is to write a user manual you won’t write integration tests for it, will you?). Common sense is always more important than strict rules.

This is What Done Means To Us

So, here it goes – our definition of “done”. As you can see it is quite generic in nature but at the same time contains some things specific to our team (like issue tracker schizophrenia uh…). It also addresses some issues that we had earlier with our code (like poorly commented TODOs or lack of information sent to project partners about some significant changes).

what_is_done
These cheat sheets now hang on the two opposite walls (so everyone can see it) and we treat them seriously, which means that if a task is marked as “done” this really means it is DONE.

A very important aspect (at least from my point of view) is that the points were discussed, changed and rearranged by all team members. Even the graphical form of these cheat sheets was done together (in fact in 3 days we had 4 different versions hanging on the walls cause we believe that details are important, so we polished it till we all agree both with the content and with the form).

What surprised me (and made me very happy!) is that my teammates set some expectations regarding “done” tasks higher than I would!

Lets say few words on some points of the cheat sheet.

FIXMEs and TODOs

These are the tags that we put into comments to mark fragments of code that should be reworked (and later find them using IDE or Maven Taglist Plugin).

  • TODO is for minor stuff. The code works, but it might and should be improved but at the moment we have some more serious things to do than to make the code pretty.
  • FIXME is for serious issues – if you don’t fix it, the code won’t work.

We decided to clear (that is to solve) all FIXMEs before the task can be marked as done. But we are less strict with TODO comments – as long as they say precisely what is to be done they are ok. So, a comment like

//TODO change it

is not permitted but

//TODO change variable name to be consistent with DAO naming conventions

is ok.
BTW., we are still discussing if it is ok to mark a task as “done” if the code still contains some TODO comments. The experience tells us that they tend to stay in the code forever (because of their low priority) which is bad. Ideally TODOs should also be removed. If we find it to be an issue, we will rethink our policy.

Code Coverage

We don’t set any strict coverage percentage. We write a lot of “integration code” which is not easily tested with unit tests, and I don’t feel like we would gain anything by setting some high threshold here. What is expected of every team member is to have a look at the coverage report in order to find untested regions and think if it is sensible to write some tests that would cover them. That is all.

Does it Work?

It is too early to say if it works because we introduced this “feature” a week ago (along with Kanban board, but this is another story).
Right now I can only say that it helps me to remember about all petty but important things that one have to do before moving on to another task. Will it have a same impact on the team? Will see about this soon (I plan to write some more on this in few weeks time).

Why do we Need it?

Answering question asked by Jacek:

why did you think you’d have to formalize what’s DONE?
Did you notice teammates don’t follow your take on it or was it something else?

Few things here.

First, as mentioned before, we started to implement Kanban. So now we have this board with few columns and the last one is called “done”. Fine, the board looks nice, but what tasks can be moved to this last column? So we needed a definition of “done”.

The other reason is that we had some issues with our code like the thing with poorly commented TODOs (that no one knows right now what should be done there). Or issues related to “code ownership” which means that each person on the team knows his code and not much more. This will be hopefully addressed by peer reviews that now have to be done before a task is finished.

I also believe that such simple thing like preparing together such a cheat sheet is very good for team health. Definitely I would like to have more stuff done together in the nearest future (I guess that is the outcome of my recent interest in Agile and Kanban).

Links

No links this time, because search will give you plenty of answers if you ask for definition of done or sth similar. Many of them really worth reading and quite inspiring. I would encourage you (and your team) to have a look at them before you start working on your own definition.

What is Your “Done”?

How do you define “done” within your team? Is it just a common sense of decency floating around in your heads, or do you have it “carved in the stone” somewhere like we do? Please comment.