Do you need to render Asciidoc documents with Spring MVC? If so, read Rendering Asciidoc Documents with Spring MVC!

What I Learned This Week (Week 40/2013)

Learning

Each week I write a blog post which describes what I learned that week. I write these blog posts for two reasons.

First, I want to keep track of my personal development and writing regular blog posts is a great way to do it.

Second, I want to share my findings with you. I hope that you can use some of them in your daily work.

Let’s get started and find out what I learned in week 40.

What I Learned in Week 40

First, Issue tracker can be used as a specification tool.

I have written earlier about the fact that email is not a good way to share information. At that time I suggested that we should create a FAQ by using a wiki. Although this is a good way to share information, the problem is that that these FAQ entries are written after the software is implemented. This causes another problem.

FAQs are a great way to describe how the software works and how it was build. The problem is that often FAQs don’t answer to the most interesting question:

Why the software is build in this way?

In the past I used to work in a project where we had two rules:

  1. A new Jira issue was created for each task. The specification of the task was written to the description of the issue.
  2. All discussion concerning this task had to happen in Jira.

At the time this felt a bit too bureaucratic to me, and I stopped following this practice when I started working for another company.

That was a mistake!

This week I realized that keeping the discussion in one place (Jira issue) has the following benefits:

  • If we need to find more information about a specific feature, we know that we can find it from the issue tracker. We don’t have to rely on the memories of the developer who implemented it. We don’t have to look information from our inboxes. This can save us from a lot of frustration.
  • If we add links to the relevant Jira issues to our Wiki documentation, we can create better documentation which describes how a feature is implemented and why it was implemented in this way.

This sounds pretty good. Right?

Second, HR can be useful. This week I had 1-2-1 discussion where we discussed about my dreams regarding software development. I know that this sounds like typical HR bullshit and before my 1-2-1 discussion I would have probably thought the same way.

However, this time I had a very different experience. When the discussion was over, I felt energized and motivated. This was a bit weird because usually these discussions have been nice but they haven’t really changed anything.

I spend some time thing about this and realized that this 1-2-1 discussion was useful because of two reasons:

  1. I described my dream before the meeting. I didn’t have to use any template and the only restriction was that I had to return the description to my team leader before the meeting.
  2. During the meeting we selected the two most important things on my list, identified the first steps which help me to reach my dream, and set a deadline for those steps.

So, what you can learn from my experience? I will answer to that question with another question.

When was the last time you thought about your dream?

If you have never done this, spend some time thinking about this and write your thoughts to a piece of paper. You might be surprised what you will learn just by doing this simple exercise.

But don’t stop there. Identify the steps which will help you to make your dream a reality and set deadline for each step.

And then… You can make your dreams come true.

Third, Writing information to a log file is not enough. We have to also be able to analyze this information.

I know that you can do a lot by using standard *nix command line tools but I am not a huge fan of this approach. These tools are good for searching information from the log files when you are solving a problem or looking for a bug from your code.

The problem is that log files have a lot of useful information and analyzing this information is beneficial in many ways. For example, we can

  • Figure out how many times specific features of our application are used.
  • Find out which is the most common exception thrown by our application.
  • Gather statistics about the response time of our application.

Basically we can analyze anything which is found from the log files, and the good thing is that we don’t have to implement this from the scratch. We can use one of the following tools for this purpose:

If you have any ideas what kind of information I should gather from my log files, please leave a comment to this blog post!

Fourth, Open source has technical debt too. This week I ran into a blog post called Don’t Let Somebody Else’s Technical Debt take you Under. It really made think about my attitude towards technical debt.

I am obsessed with technical debt. The problem is that I am obsessed with my own technical debt. I have to confess that I haven’t paid a lot of attention to the technical debt of open source libraries and frameworks which are used in my projects. Jim Bird helped me to realize that this is irresponsible. Also, he gives good tips on how to solve or avoid this problem.

Here is my tip:

If you are using Maven, you can use the Versions Maven plugin to find out which dependencies or plugins have newer versions available. Run the plugin once a week and update the outdated dependencies and plugins. I know that doesn’t sound like much but it is a good start.

Fifth, The time of standalone diagram editors is over. This week I started a task which is probably quite familiar to all software engineers. I wanted to find a reasonable prized diagram editor for OS X. Although I did find a few pretty good options (one of them was Diagrammix), I realized that there are many web based alternatives as well (Thanks to everyone who gave their opinion at Facebook).

These alternatives are:

When I was evaluating these applications, I realized that all of them have the features which I need. In other words, instead of evaluating standalone applications, I ended up thinking about this question:

Does a standalone application have any advantages over web based application?

The only “advantage” which I could figure out was that a standalone application might have a better user interface than a web based application.

Was this enough for me? No. I ended up choosing Creately because of two reasons:

  1. Its user interface is really simple.
  2. Their pricing is really attractive and the personal plan has the same features than the other plans (except team management of course).

It was interesting to see that cloud based applications are getting better and better. I wonder when I will see the first usable cloud based IDE (the IntelliJ Idea has set the bar pretty high for me).

What Did You Learn This Week?

Share your learning experiences or other comments on the comment section.

About the Author

Petri Kainulainen is passionate about software development and continuous improvement. He is specialized in software development with the Spring Framework and is the author of Spring Data book.

About Petri Kainulainen →

4 comments… add one

Leave a Comment