Provide Document Feedback for Efficiency

When providing document reviews with comments or track changes, most people start writing their comments as they read through. This is perfectly natural and recommended, as capturing your thoughts immediately is the best way to ensure they aren’t forgotten. That said…

As you read through the document, some of your comments made earlier may be addressed later in the document. If you think the content should be moved, this is a good time to point that out, referring back to your earlier comment. If not, take the time to move the comment to the appropriate point, or revise it accordingly.

Short-term memory varies between person to person and even context to context. A comment provide early in the doc is likely to be remembered and reference back when it discovered at the end that it was not necessary if the review is done in a single sitting or as part of a very focused project. Then again, someone stopping by to say “hi” or an IM popping up immediately after writing a comment can pop the memory out of the short term queue and only invoke vague familiarity if the concept is addressed later. Because of this unplanned and unschedulable variation in memory reliability, I suggest re-reading through all comments prior to submitting them. It will (hopefully) catch those forgotten inputs that should be revised in the context of the entire document so that the sent input is concise.

The value of concise input is two fold: It makes it easier for the person receiving the feedback to apply it where needed, and it avoids the frustration of seeing comments from a review that the author knows are not valid because they are addressed later on.

© Scott S. Nelson

Replace Auto Dates in Templates

Many templates include a date that is based on the current date. In the good ole days, when a designated file type for a template was used and the file was saved as a standard file, that date would stop updating automatically.

These days, most templates are just a previous file where the original content was stripped and labelled as a template, and even those that are specified as template types still keep the date updating after saving to a file. This makes the date of the content unknown, the opposite of the value of including a date.

For the sake of those who want to keep content in context, please develop the habit of replacing the auto-date with the actual date when publishing documents.

In some templates, fixing the date is hard to do, especially if someone has locked aspects of template with good intentions (and annoying consequences). In that case, overlay text on top of it with the correct date with the background fill blocking out the auto date.

© Scott S. Nelson

Failure to plan communications is communicating a plan to miscommunicate

Most project charters include a communication plan, and it generally consists of who to communicate what to. What is often missing is the how, which is why many teams find themselves with endless email chains where the subject stopped reflecting the content a dozen messages down the thread.

Many enterprises offer multiple platforms, such as Slack, Teams, SharePoint, Confluence, Jira, ADO, etc. If there is a choice, determine how the team will most efficiently interact and then pick the tool that has the best features supporting those interactions. If there isn’t a choice (such as when a company may have several tools but a department only has one), be sure to keep some key communication and collaboration practices in mind as you plan its usage.


Group topics in an intuitive manner. What is intuitive generally versus only for insiders can be different. If the team membership will fluctuate frequently, opt for intuitive for someone who needs to be productive quickly with little help. Long-term teams should evolve the taxonomy over time to foster productivity.


We all get busy and skim our in box or project sites looking for what jumps out at us. Consistent formatting can help. Have predefined prefixes such as “ACTION REQUIRED:” or “No Response Necessary:” can help people see what is important and prioritize reading and responding. The range of formats can be very broad, so a full list is not appropriate here.

Read Me

The best of plans do not survive the first release. The taxonomy may fall out of date. Determine the most common entry point to the team collaboration and communication platform and post and pint a Read Me that explain the purpose of the team, the organization of the platform, and who to contact for help by topic.


Often a project will have multiple channels: The project management tool, the wiki, and IM client, email (sparingly). The team should decide which channel to use for what and gently remind people who use the wrong channel where the appropriate channel is and why.

© Scott S. Nelson

Agile is not Ready, Fire, Aim

(Disclaimer: this article is not about what Agile is, the term is used only for blatant marketing purposes. Some principles were violated in the writing of this post)

A colleague of mine recently said something to the effect of “the goal of agile is faster delivery”.  This is a common misconception fostered by the improved velocity that agile teams can achieve in the context of enhancing software with new or improved features. The goal of agile is higher quality software, where quality is defined as meeting the intended functionality in a reliable manner. (lots of paraphrasing there, so please don’t flame me about accuracy). Another root of this misconception is that people who do not participate in agile projects (sometimes referred to as chickens) want agile to be about time-to-market (I’m working on a longer rant on that topic alone). Just like some people want agile to eliminate the need for planning and documentation, not be because these things are not critical (apologies for the double negative), but because they are tedious. They are certainly not mindful, because one focuses on the past and the other on the future, and we all want our features right now. Agile without planning and documentation leads to technical debt (something I grumbled about recently, with more to come).

Technical debt is the driver behind this particular rant, as I recently observed the creation of an equivalent jumbo mortgage with an early balloon payment due. In the same recent article linked earlier I mentioned how sometimes a platform migration is driven by a desire to get out of unacknowledged tech debt. In this instance, I witnessed the debt being incurred as a result of the migration. Specifically, the approach was taken to manually migrate data that was in immediate use while configuring the application without documentation in order to get into production as quickly as possible (the root cause of most tech debt). The idea was to migrate the rest of the data later. This migration, like many these days, was from one SaaS to another. The secret to a maintainable and extensible SaaS application is including flex fields in the data model. These are fields that have no pre-defined purpose so that customers can use them for customization and the vendor can avoid the hairball that results from customizing for each customer. The downside to this data model is that if the customer changes default labels and makes heavy use of the flex fields without documenting all of these changes, the data migration effort increases several-fold.

So, here is a real-world example of the impact of technical debt in a compressed timeline that is easy to follow: Short cuts were taken to quickly “realize value” from a new platform, and then to fully taken advantage of the platform subsequent efforts are increased, resulting in a much higher total cost and longer timeline to completion to get that short term win. None of this is the result of bad people or malicious intent, in fact, quite the opposite. It is the result of a “modern” business culture that has evolved to focus on quarterly earnings. It also explains why businesses that really want to innovate either do so before their IPO or go private to get back on track. It’s not because software can’t be done right in a standard corporate structure, but that “Continuous attention to technical excellence and good design enhances agility”.

© Scott S. Nelson