Posts Tagged ‘Documentation’

22 March

CHM Text Searches – Lesson Learned

The current project I am working on involves working on the CHM (Microsoft Help Files) for Windows Embedded Standard 7. This was a project underway before I joined the team and it had even changed managers during that time, which always creates at least a bit of chaos.

We just dropped our CHM files to the product team for integration last week and then discovered we had not completely purged the contents of the project’s internal name and prior release same in favor of the final release name. This happened despite having myself and four other people all search the Help for the string. It even happened despite a tool that would automatically check for the strings you tell it to at build time.

After dealing with the aftermath and rebuild/redrop (my boss was out of town), I looked into why this had happened and discovered I had let my tester mindset go to sleep and had not really thought in depth about how the searches were being done and the potential holes in these approaches.

The stage is set by:

  • The tool was checking for the term in the files at build time.
  • The individual searches done ad-hoc were using the search functionality provided in the Help by Windows when reading the CHM file.

The following discoveries were made as we looked into where this failed:

  • The tool does not check the index. Several instances of terms entered into the tool were found in the index.
  • Not all “bad terms” were entered into the tool’s database.
  • The Search functionality in Help does not search the index and no one thought to look there because the index was generated from files thought to be clean.
  • The Search functionality in Help is a regex-base search. All ad hoc searches were done with the same string, but no one thought to look for substrings with use of a wildcard before, after, or both in relation to the “bad string.” This meant no instances where the “bad string” was a substring could be found, though quite a few existed.

It seems obvious now, of course, but it really does help to look at these occurrences and see what the root cause was so that it can be caught in the future. In this case, we took away the following actions for the next release:

  • All terms must be entered in the tool’s database.
  • The CHM must be decompiled and the HTML contents searched for the “bad terms”. This will catch substrings and index occurrences.
  • Ad hoc searching must be done with wildcards and regex to also look for string and substring occurences.

Lesson learned and I paid the price. Both in terms of this instance’s particular issues and in terms of forgetting to look for holes in the process/testing – even if it’s not my job.

15 December

Scrum on a Software Documentation Team

In April 2009, I changed roles at work from being a tester to being a contract programmer-writer. As many of you know, this is not my first experience with writing or instructional design, but it is my first experience with being an official member of a documentation team.

The product team we work with is using Scrum and when I joined the documentation team, it was advertised as also using Scrum. Only when I joined did I discover that the team was using a mutant form of Scrum + Waterfall that could perhaps best be described as Stuff Flowing Downhill at Great Velocity and With Little Organization. The only real resemblance to Scrum was the daily “huddle” – except it typically lasted a half-hour for a team of four and was more concerned with approaches than purely status.

The first several months were confusing and prone to bouts of frustration. Work was getting done but, while I couldn’t speak for the other team members, I was certainly not signing up for my own deliverables and setting my own timeframe. I was catching things as they were being tossed at me. Since my personality doesn’t allow me to just sit back and not become personally invested in a project, I offered to help move my team more toward proven Scrum practices but my offers were not accepted. Instead we muddled along and I fought back my desire to help :)

Mind you, I do not think this was because of any ill will or evil intent but I think the situation had roots more in the inexperience of the lead that hired me and in the fact that lead did not have training in Scrum. The lead had read a book about Scrum but I’m not sure which. I was the only team member who had done significant reading and investigation of Scrum, let alone taken a class on it.

About three to four months after I joined the team, the lead that hired me resigned and I gained a new lead. This new lead had no experience with Scrum but did have a lot more experience with leading a documentation team and shipping product documentation. He really got tossed into the morass with a team he didn’t know and a project already at risk. Our product team had no idea what we were doing and where we were and thus were (justifiably) nervous. The lead had no idea where we were either and what had or had not been done. There was no plan, there was process documentation beyond some emails and it was a mess. One lead, a team of three contractors and a huge lot of bugs and legacy documentation – it didn’t look good, I admit.

The day I got the email of the change in leadership, I stopped by his office and introduced myself, then told the new lead I had a lot of feedback on the team, the project and our processes that I’d love to share with him whenever he was ready. He just nodded, looking a bit shell-shocked, and said to give him a few days to get a handle on what was going on. It actually took a few weeks but I was able to start feeding him bits of Scrum processes and suggesting changes to help us. After a few months of introducing change, as well as taking a full time job with my team instead of my contract job, we’re now running a much more Scrum process.

We put up a corkboard in the new lead’s office and went with the visibility of notecards and columns for stages of our process – Writing, Initial Edit, Tech Review, Final Edit, Done. Each team member was responsible for moving their cards and the standup was used for real status updates and blocking issues only. No more talking about how to do something or implementations. I took over running the standups and serving as the Scrum Boss to keep the meeting on track. We stuck with one week sprints because we HAD to get and stay on track and because the documentation team needed to learn Scrum. I felt longer than a week’s sprint was too long given the black-hole history of the team members’ deliverables.

I wrote up a process document to send to the product team members so they would know what our dates are and how the documentation process works. This helped to clear up misperceptions and helped them understand what to expect.

Each of our team members began attending the weekly leads meeting that relates to what section of the documentation they are working on. This helped increase visibility and cooperation with the product team members.

The next step took a lot longer than I’d have liked. I had been pushing my lead into the role of Product Owner. He had the best knowledge of the documentation process overall, the best knowledge and access to the product team’s schedules and needs. And he was the boss :) He was really nervous at not knowing exactly where we were, how we were doing, what progress we were making, etc. His reaction to this nervousness was to suggest scrapping Scrum and going back to waterfall but he did realize it wouldn’t work when I pointed out that it would not help at all to make the switch – instead we would have to start over again. We made a pact to give Scrum a chance.

A month had passed without the product backlog being generated by my lead, despite my promptings. I believe, in part, this was because he wasn’t sure what to do but also because he was involved in trying to hire another team member as well as dealing with the other products he still owned as well as mine. In the third week of my being a full time employee again, I took all the information I had on the parts of the documentation project I owned and made a backlog spreadsheet for it. I wrote some assumption at the top, prioritized in batches according to those assumptions, and did a rough cost estimate on each line item. Not surprisingly, I had about twice as much work TO do as I did time to DO it in.

Once my lead had seen the spreadsheet, the lightbulb really came on. He worked with the other two writers to create the same sort of product backlog for their sections. Because we don’t have enough people for true cross-training, we kept the sections separate for now.

The last two days have been the fruits of all that labor. My lead seemed a bit worried at how the message would be received that we were NOT going to get everything done by the release date. My mantra was constantly “better the devil we know” – at least now we knew exactly where we were, could communicate that and could communicate progress. We came up with a plan for the items that would not make the cut as well. Each project team group has been great when presented with our backlog list. This was the transparency they’d been wanting all along.

Right now I’m waiting for the product team to look at the list items and calling out any changes made in the batch prioritizations I’d made. In the meantime, I’m working from the top of the list.

We stopped the sprint board when I was interviewing, the Thanksgiving holidays hit along with a product preview release, and things got out of hand. My lead has already agreed it will be restarted right after the Christmas holidays. In the meantime, people are working from their backlog lists as well and the standups are reporting status from the writers to the lead.

My lead has gained enough time back to be able to do some writing again, instead of only managing. We will be on the same page as the product team and will have set reasonable expectations of what we will produce by ship time. We even have a plan of how to handle the post-release work that must be done.

I’ve not announced it yet but my boss will soon find out about the sprint retrospectives we need to have :)

16 July

A Rant About Documentation

As both an author and a consumer of technical documentation as well as having some background in instructional design, I have some strong opinions about the role of documentation for a product. Over a decade in testing has also had an effect on how I view that documentation.

The most basic documentation is the help file that ships with the product. In Microsoft products, this is called a .chm (“chum”) file. Yes, I’ve probably thought of my share of bad jokes about that slang, too. I find myself currently involved in cleaning up the previously written .chm file for a new product as well as authoring new content for it and there have been some challenges.

Out of these challenges have come the start of my own personal list of DOs and DON’Ts for technical documentation.

  • DO know your consumer and know HOW they use the product to do their jobs.
  • DON’T sacrifice your reference sections in favor of only user story or scenario-based content.
  • DO use a more conversational voice to make the documentation easier to consume.
  • DO review customer feedback for opportunities to update your documentation to cover problem areas when appropriate.
  • DO produce other documentation besides just the .chm help files.
  • DON’T use the excuse of having other documentation to short-change the help files.
  • DO edit for professional voice and errors.
  • DON’T over-edit and lose technical accuracy in favor of prettiness of language.
  • DO offer tips and make sure gotchas are included.
  • DO make content easily findable and clearly identifiable by the consumers.
  • DO have your content thoroughly reviewed by the product team.
  • DON’T let the process of creating documentation get in the way of doing the right thing for the customer.

My background in shipping products has given me some valuable insight and gives me a solid base on which to work with the product team. I understand what they are talking about and don’t need a lot of hand-holding. They know I take deadlines seriously and am honest with them about where I am on my deliverables.

But I think documentation teams also really need to be able to turn on a dime. Things can change rapidly and you have to be able to roll with those changes.

Processes are required, both within the documentation team and where the documentation team has to interact with the product development team, but you really have to watch for signs that the process may be causing more overhead and pain that it’s solving. When a five minute task takes three days, an email thread of ten or more emails plus several requests being filed…you may have a problem.

You have to keep your eyes on the prize. The prize is excellent documentation to assist your consumers – not how well processes were followed or how many you have. No one will judge your documentation by how many people worked on it, how many processes were followed, who did what tasks or what tools were used to produce it. All consumers care about is how well it meets their needs.