Practical Software Engineering

Groups large and small use Wikis to capture and share knowledge. As you read page after page of a Wiki, you notice that some pages are good, but others not so much. What traits distinguish a good Wiki page from its mediocre cousins? Here are the four key factors that make a Wiki page good.

A good Wiki page:

1. Focuses on one idea,
2. Provides context for all outgoing links and attachments,
3. Uses attachments wisely, and is
4. Short (500 to 1,000 words).

1. Focus the page on one idea only. Help your reader quickly realize that they are looking at the right page by focusing the page on a well identified topic, subject, or idea. For all the ideas that lay outside of its focus use references to other pages. This will help provide additional material to your readers and will clearly delineate the boundaries of your page.

2. Provide context in the body of the page for all outgoing links and attachments. Weave your content together into a coherent whole with links in context. See my previous post on why a good Wiki tells a story. You need to weave your pages together by providing a context for each outgoing link. The context doesn’t have to be much: a half sentence describing where your link is going, a short paragraph describing the attachment, or a heading for a list of links.

While it easy to quickly create additional pages (sometimes also known as child-pages, or sub-pages) without the link in context, they are not very helpful, and often are difficult to find. Your readers need to know in what order to look at the other pages, or why should they look at those pages. You must provide the necessary guidance by explaining the reasons for any link, and creating a context for them as well. The context will aid searching, and more-importantly, finding, your pages, too.

3. Use attachments wisely, that is: sparingly. When you have a plain text, or rich text document, you need to import that document as a Wiki page. Do not turn the document into an attachment. Just one extra step between your readers and the knowledge they seek may stop them from looking.

Most Wikis still have trouble indexing attachments. Some attachments, notably pictures, drawings don’t lend themselves to easy indexing, therefore if you want to find an attachment, you’ll have to find it based on the context of the page that it is attached to.

4. Keep the page short (500 to 1,000 words). Your readers access the Wiki pages on the screen. Make it easy on them. Short pages help the reader see the entire page at once, or bookmark just the right information for later reference.

“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”
- Antoine de Saint-Exupery

Here are some good Wiki pages from Wikipedia:

1. Atomic Commit: Concise, to the point, with links in context and focused.
2. Two-Phase Commit Protocol: Not short, however kept focused on the topic, with links in context for further information. If the subject demands, you can go longer, just keep in mind that you might loose your reader…

Help your team by writing outstanding Wiki pages! Your team will thank you for them.

Planning is a topic that I find myself coming back to time and time again. I’m asked enough questions about it so I decided to write down some of the answers. Folks who have not had to do any planning are stumped when asked to make a plan. I found that planning can be rather intimidating until you start with writing down what are the deliverables and what is the time frame. This will get your thinking started in the right direction. This and upcoming notes are here to help you get started on planning your own work.

Consider this scenario: you get assigned to a project, but instead of being the one you dreaded, this is one that you are excited about! The technical lead held an effective iteration kick-off meeting. You picked up work on a couple of features that you thought were really cool. You are expected to make a commitment to deliver the features at the end of the two-week iteration. Can you do it? How sure are you? How do you begin to build a plan for your work?

The first step is to decide how much time you can afford to spend on each feature.

1. Kickoff (1 day)
2. First feature (4 days)
3. Second feature (4 days)
4. Wrap up and demo (1 day)

Next, estimate how you intend to spend the 4 days you budgeted for each feature. You must think of your time as money. Spend it well. Let’s suppose that your technical lead had done a good job coming up with granular features, and you can indeed implement each feature in 2-4 days. Here is how you can “spend” your time during the iteration:

1. Iteration kick-off meeting (1/2 day)
2. Plan the iteration (1/2 day)
3. Design the first feature (1 day)
4. Implement the first feature (1 1/2 days)
5. Test the first feature (1/2 days)
6. Prototype the second feature (1 day)
7. Design the second feature (1/2 day)
8. Implement the second feature (1 1/2 days)}
9. Test the second feature (1/2 day)
10. Fix the defects found in integration & system test (1 day)
11. Demo the iteration results to the team. (1/2 day)
12. Buffer (1 day)

That’s it. This is your rough plan for the iteration. If you wish, you can call this a time budget and not a plan. If you are to deliver the features at the end of the two weeks, this is all the time you have. The key point is that this plan, even with its limited details, shows you what time can you afford to spend on each feature. The presence of the buffer in your plan is the clearest acknowledgment that you don’t yet know enough. When new things come about, you won’t have to replan your entire plan. You can just eat into your buffer. However, once your buffer gets exhausted, then you need to rework your plan.

Looking at this plan you might think that you won’t be looking at times at both features. That should not be the case, especially if they are related. It just means that now you have a way to get the work started. As you get into the details of the work, you will refine this plan. For ideas on how to move forward take a look at What do you know? and Guidelines for Detailed Planning. There are many other aspects of planning, e.g. getting some data on how you are doing, and how to improve your planning skills. For now though, just get started. As the old Chinese proverb puts it:

“The one thousand mile journey starts with the first step.”

Ready! Set! Plan!

The need to understand a software system comes up many times during the career of a software professional. A common situation is that you have just been assigned to a new software project. You’ll be working on a system that is unknown to you. Your first task is to fix a defect. Where do you start?

Undoubtedly, you first have to understand the system, or at least understand a portion of the system that you have to modify. Without understanding the system your changes will result in new defects. Here is how to get started:

1. Identify which use case is affected by the defect. The defect report should give you a lot of clues about this. If a written use case doesn’t exist, then write it. Expand out those areas of the use case where the defect is. Ask folks who worked on the system to review the use case that you wrote. At least ask some of your peers to review it.
2. Draw a block diagram of the system. Start with the externally identifiable structure. Are there any libraries, packages, modules of code that stand alone? Draw a rectangle for each module. Draw a line between them for each dependency that you find. Have a peer review this for you as well.
3. Draw a sequence diagram for key interactions from the use case. Of special interest are initialization sequences, the action sequence of the use case that has the defect, and any interrupt or service request sequences that might influence the action sequence’s outcome. Walk a peer through the sequence diagrams and see if they find anything missing from them.
4. Identify which modules of the software system are involved in the use case. Identify the source files that belong to those modules. Look through the files, assess their sizes, and see how long will it take for you to grasp them. You can review code at about 200 lines of code per hour, so it will take you about 5 hours to understand 1,000 lines of code, or about 25 printed pages.
5. Identify the most likely parts that you will be working on. What files will you have to change? Ensure that you can check those out of the revision control system. Setup a private branch for your fix to avoid disturbing other people’s work.

By capturing a use case, a system diagram, and a few sequence diagrams you are well on your way toward understanding the system. These artifacts help you identify the root cause of the defect as well as provide you the starting point to devise and implement a fix. There is more to understanding a system, but this is the minimum in order to improve your odds of success!

In Living with Constraints, I touched on a topic that is on the mind of software people: managers and developers alike. The time constraint, also known as “The Deadline” is of particular angst for some technical people.

Many people have a fear of deadlines. They are as frightened by them, as they are of speaking in public. For developers, the mastery of both can be a critical success factor. For managers, they are a survival skill.

What happens if you have a problem with deadlines? Maybe right now you have difficulty meeting the deadlines thrown at you, and you have given up on being able to meet them. Not meeting deadlines can be detrimental to your business and your career. So, how do you get out of this?

The age old advice is right on the mark: start out by setting small deadlines that you can meet. Get early wins. The only way you can get better at meeting deadlines is… by actually setting and meeting deadlines.

Along the way it helps if you remind yourself as to why are you doing this: you are getting better at meeting deadlines, because deadlines are nothing more than commitments. The world runs on commitments. Both your business and personal life depend on commitments. Your ability to succeed depends on your ability to make and meet commitments. Other people count on your output. You shouldn’t let them down. And you count on commitments from others. Once the chain reaction of missed commitments and deadlines starts, the endeavor can spiral out of control.

What is a good first commitment? Select a deliverable that can be done in 30 minutes or less. Make a commitment to yourself at the beginning of the day that you complete the work by the end of the day. That’s your first deadline. Here is an example: “I provide feedback to John on the white paper by 5 pm today.” Repeat this for a week.

Once you successfully meet your deadline every day for a week, then set yourself a slightly more ambitious goal. Make the next deadline one that involves between 5 to 10 mini deadlines to deliver on a more complex deliverable (requiring about 5 hours of total work). Then work yourself up to 20, 40, 50 hours of commitments involving many intermediate deadlines. Meet each one, and see your confidence grow.

As you set and meet commitments the word will get out that you are a person to trust with projects. You will become every more successful. And you will see your career take off.

______

PS: The Deadline is a book of fiction by Tom DeMarco. The author illustrates many issues surrounding software development. The main character of the book, Mr. Webster Tompkins, the project manager, sets up three teams for each product to develop the same system with different methods. Make time to read it.

You heard of Wikis. You might be using them daily. They are everywhere you look. Unfortunately, quite a few of them are not as useful as they could be. Over the years many of them became dumping grounds for page after page. Now it is almost impossible to figure out what those mean or how they are related. Other Wikis languish for lack of participation. How can you make your Wiki work better for your group of collaborators? Make the Wiki tell a story!

How to turn your Wiki into an engaging story? Follow the advice from story tellers:

1. Decide on the story you want to tell,
2. Create a story line that engages your audience,
3. Tie your pages together into a coherent whole.

1. Decide on the story. What’s the purpose of your Wiki? Is it for a project? Or just to keep track of your ideas? Or to support a product? Whatever it might be, decide on a story that you’d like to tell and build a plot for it. The plot should include the main story line and will include multiple secondary plots. Once you have the plot, write the summary of the story on your starting page in the Wiki.

2. Create a story line. All good Wikis tell a story. Be it the story of a project or of something else. They draw you in and make you click on page after page because they have the information that you want. And where the information is missing a good Wiki compels you to add the missing paragraphs and pages to make the story complete.

3. Tie your pages together into a coherent whole. Decide on a starting point for your Wiki. This is pretty easy since all Wikis have a Home or Main page that serves as the start. As you are writing the “plot” of the story, lay it out across multiple pages, but always make sure that you link one page to another. Before linking to a lengthy “sub-story” in your Wiki, include a summary of that story, and let the user decide if they would want to follow on that link, or just skip to the next chapter.

Practice, practice, practice! Just like with anything else, you’ll get better at writing if you practice. The book Writing the Natural Way by Gabrielle Rico, Ph.D. can help.