Blog

Tomorrow (Tue, May 18) there's an excellent chance to hear one of the best bloggers and practitioners on the topic of Product Management - Steve Johnson of Pragmatic Marketing is giving a talk to the Cambridge Product Management Group.

The Pragmatic Marketing Framework is a design classic, and mandatory reading for anyone in the field.

Much of my work has been in a Product Manager role even though I didn't always have that title at the time. In the high-tech and semiconductor sector, it was often a simple split between Marketing (the people who set up tradeshows and talk to customers) and Project Managers (the engineers who get the product out on time). Smart readers know this conflates Product Marketing and Product Management. Really smart ones will see the slip in terminology between Project and Product Management. There is a difference between the three titles, and the Pragmatic Marketing website will answer all questions.

Thinking about tomorrow's event made me consider what makes Product Management so difficult and frequently prone to failure?

My inclination is that there are 3 basic problems that make even good intentions into the paving stones leading to Product Hell.

1. Lack of a product workspace containing technical and commercial documentation makes it difficult or impossible for new joiners to become familiar with the product. Before you know it, the old issue of "knowledge is power" raises its head. Or, "Scientia potentia est", if you want to be fancy. Gaps appear in product documentation, and this usually means a shortfall in marketing collateral when it is most needed.
2. Lack of a standard process or workflow causes product decisions to be made in an ad hoc way. At best, it is inefficent as good practices have to be re-discovered. At worst, product decision-making quality varies between instances.
3. Release fragmentation leading to / caused by customer variants makes for a configuration management nightmare. Bringing all the customer versions back into one main branch or trunk build can make publishing a future roadmap very hard to achieve.

For the past 10 years, the solution to these problems for me has been to use CogniDox. Here are a couple of illustrated examples of ways that CogniDox has helped me and other Product Managers / Project Managers have an easier time of it.

The first example is creating a category or workspace for all documents relevant to the project or product release. This can have as many sub-categories as needed, as long as the core requirement is met - a logical place to start when you want to navigate through the product documents.

There's nothing revolutionary about this, but the number of companies I encounter who don't have a structured, common repository for product documents means I have to mention it. The example above illustrates how the category contains everything - software release packages included - that will go into the release.

The second example is something we call a "document holder" in CogniDox. It's a type of document written in XML that has placeholders for other documents. Other documents can be any file format, including video tutorials if you want. 

As you can see, the web page view (icon on the left) is automatically created from the XML file (icon on the right).It's especially helpful because it ensures that the document actually exists, and/or makes sure that correct process is followed e.g. you can't release a draft version, it has to be issued and approved.

What we've tended to do is create a document holder that reflects the structure and contents of the category, because an important point is that we can release the document holder as a deliverable to customers. It will help them understand the product's structure.

When a user from a customer company logs into the customer web portal access that we provide as part of standard CogniDox, they see the product documents that the Product Manager has licensed to them.

If we create one of these per product release or release variant, we know that the licensing manager module in CogniDox will automatically ensure that users only see what we have licensed them to see. There's less danger that the product variants will cause us to make an error of including a file we shouldn't, or leaving out something critical and looking quite unprofessional as a result.

When we start a new project or release, we can copy the category structure from a similar product that we know worked well. Best practices start to become reinforced without any need for heavy-handed mandates.

The next example that I want to cover is the use of Reports to help a Product (or Project) Manager understand the product status. These reports provide a unfied console to assess projects in the pre-release process. If I have a Gate 1 milestone next week and we have collectively agreed that twenty documents will be prepared in support of it, then I can see at a glance how many have been uploaded, reviewed, issued and approved. It saves valuable time at the Gate review meeting itself.

CogniDox tools have been critical to me and others as we make Product releases, and have become as essential as our software code version control or bug tracking systems.

The analysis and research company Basex published a survey this week entitled "The Document Jungle". It is a survey of the documentation habits of 300 knowledge workers.

They reported that each person produces 1 or 2 short documents per day and were called on to review around 3 to 5 documents per week. Some documents are not sent for review or sent to just one co-worker. The majority are circulated for review.

When it comes to circulating documents for review, 60% of the time they are sent as email attachments. The outcome may sound familiar to you - comments come back and have to be manually collated by the editor; there is a high percentage of error as edits get missed or comments overlooked; and comments are not returned in a timely manner.

25% of the survey respondents deliberately leave colleagues off review lists as they know they will slow down the review process. Personal experience tells us that, in the rush to get a major design document ready for a review deadline, it isn't easy to focus on the big picture of why we wanted it reviewed in the first place. "Speak now or forever hold your peace" isn't a very good design strategy, believe it or not.

We have a strong set of features in CogniDox to support the document review workflow, but we are frequently asked by users to include more. In the latest release (v8.2), for example, we added a better way for project leads to obtain reports on the status of documents sent out for review and/or approval. I can create a spreadsheet report by user that shows how many documents they've been asked to review, how many are outstanding (and are overdue on deadlines). I can do the same thing for document approvals.

It's a handy little dashboard-type report that gives even better feedback in larger companies with complex inter-departmental relationships. Routing every design document through a small set of design architects may show up in the stats - these individuals have a large review workload and they are not able to keep up. Good supporting data for your next New Hire request application...

Here are 8 suggestions for how to improve design document reviews in your company:

1. Get a Document Management System instead of using e-mail attachments. You have a very low probability of success in improving your document review process using an email-based solution.
2. Think before you add people to your list of reviewers. Do you really want them to comment, or are you just notifying them that the document is available? CogniDox separates reviewers from people to be notified - use it explicitly.
3. Use the comments field to direct your reviewers. Are you more concerned about technical accuracy in this issue than you are about editorial style? I need to know that as a reviewer. It may make sense to assign sections to individual reviewers - make that explicit.
4. Set meaningful deadlines. If you really need the draft press release reviewed by the end of one working day, say so.
5. Use email to send notifications that documents are ready for review. Include URL links that enable reviewers to quickly and easily navigate to the document review pages in your DMS. It may help to encourage timely reviews if people can see that other reviewers are making progress on their review tasks. Send automated 'nagging' mails when deadlines are missed.
6. Agree a set of terms applicable to your workgroup, department or (ideally) your company. If I reject your draft document and request changes, is that the same as if I accept your draft but leave a set of comments that I expect you to consider and include?
7. It's easier to read review history comments when displayed "in-line" by version and contributor threads. CogniDox allows users to select a document version and read the threads of comments made on each. Other tools such as Google Wave are addressing the same opportunity.
8. Build accountability into the document review process. Make document readiness an explicit part of any new Product Gate Process or QA strategy. Remember, poor documents end up costing extra time and money. Worse, customers may get to read them.

At an event hosted by the Electronics KTN and DSP Valley I had a conversation with the CEO of Easics NV about the suitability of the Agile methodology for embedded software development. One thing we agree works well is the use of Continuous Integration.

For anyone unfamiliar with the concept, Continuous Integration is a software development practice that requires regular and frequent (e.g. daily) check-in of new code. It requires a code repository with minimal branching, and the evolving repository (aka "top of tree") should be built and tested on an equally regular basis.

One impact on software team resource planning is that it is a very good idea to include tasks that make the build self-testing, and reporting tools for informing the rest of the team about the results of those tests. There are tools available that can help.

It calls for integration into the daily project plan of each developer. For example, if yesterday's check-in broke the overnight build, then today's first priority is to fix it. That way, all other team members can continually integrate and test their changes against the incremental build.

The #1 benefit is that it saves surprises and unplanned effort during the software integration phase, which in the traditional software waterfall method comes late in the development cycle. But it also fits well with other elements of the Agile method, such as using short, focused user stories as the means of capturing requirements, and the fast turnaround of feature development associated with Scrum.

There are other areas of Agile less compatible with Embedded Software, at least as it applies to the Electronics industry. There is nothing in Agile that formally opposes system documentation, but many proponents de-emphasize it. This may be fine for e.g. website development, but writing the software sections of a Silicon Specification document is not optional in chip development. It's also not obvious how you would express a DSP algorithm requirement in terms of a user story.

The way some "Agilists" talk about documentation is illuminating, for example:

"the economic difficulties of the past months have finally put waterfall out of its misery; now more than ever, long requirements phases and vaporous up-front documentation aren't acceptable" - Cennydd Bowles

"Friends build products; enemies only build documents" - Steve Johnson 

As I say above, there is nothing intrinsic in Agile that means documentation isn't important, but when the emphasis is on co-located teams, requirements analysis by card sorting and the prototyping of working code; it isn't a major surprise that documentation can be downgraded.

Interestingly, the technical writers that I've spoken to about this are not especially big on Agile - they seem far more interested in modularity and the re-use of structured XML components than they are in the methodology of production.

Generally, documentation is still the bane of software development. Jerry Weinberg summed it up in 1971:

"Documentation is the castor oil of programming. Managers think it is good for programmers, and programmers hate it". There is still a tendency to try to avoid doing it.

Sometimes, a Wiki can be used to assist the software development team. This tends to be better at the "how" of software production rather than the "why". For example, a Wiki describing how to run the automated test build will probably be well-used and maintained. Documentation about the user commands and error conditions has a lower probability of maintenance.

The way around this is to go with the psychology of the programmer - their locus of attention will be on the code and the aim should be to make the documentation fit around that. An ideal version of this might be the idea of Literate Programming proposed by Don Knuth in the 1980s. The output of the developer's labour is a composite of executable code and (human) documentation.

The next step is then to ‘harvest' this documentation so that it can be presented in the formats that humans prefer - user guides, quick start manuals, on-line help, etc.

There are a few interesting examples of tools that try to achieve this. For example, Doxygen is an open source tool that will extract help text and APIs from source code (C, C++, Java, many other languages) and auto-generate documentation from it in HTML, PDF, RTF, LaTeX, and other formats. In teams I've worked with, it was used to document an embedded RTOS and a device driver framework. It seemed to work well for that purpose, but it required a conscious decision to use it as part of the coding. I've never seen it used for end-user documentation, and am unable to say how well it might work.

Another example is the Publican tool that Red Hat made available as open source. This has the right idea - taking XML and turning it into HTML and PDF with style sheets, but it is complex to learn and is specific to Red Hat's DocBook.

I've read that Microsoft Sandcastle is a similar documentation generator that automatically produces MSDN style documentation from .NET development. However, I have never seen it used in software development so can't really comment.

The conclusion I feel is that there is still considerable room for improvement in this area.