Most of my IT career has been as a consultant and a manger of consultants. Over the years I have established some patterns to follow that I find helpful in making projects and technology easier in the long run. I sometimes share these in mentoring sessions and have heard often enough “you should write that down” where I started to.
I am still writing these concepts down, and while they originate from a consulting perspective they translate to every day practices beyond consulting.
At the time of this writing (not reflected by the pub date), I am re-vamping this site. Part of the update is moving this content from a standard page to a category page. The navigation will change to reflect that when it is either complete or well along.
There should be at least one person involved with any given proposal that has no other task than working on the proposal. This person does not need to be the most senior on the proposal team or even the “owner”. The key role of this dedicated resource is to track all contributions and ensure that the final proposal has a single voice and standard format (even if the actual work of making that happen is delegated). This goes double if the proposal is for a public RFP.
There should be books written on this topic. Many, and all with fewer than four paragraphs or no one will finish them.
Whenever someone is compelled to label something as “common sense”, everyone agrees even though it is clear that it is not all that common because it had to be called out. That can apply to just about anything I have to say about email. So here are a few common sense concepts about email:
While some people are good at making context shifts in a conversation, there are many people who find switching topics difficult. In verbal communication a missed context switch will often result in a response being framed in the previous context. The same can happen in emails, or (worse) the new context is simply ignored. Why is it worse when ignored? Because when a subsequent email requests a response to the ignored/skipped topic, the recipient will either again miss it or reply that they have already responded. This is neither obstinance nor resistance; it is how their brain perceives it. Keeping to a single topic may initially seem inefficient (and it is if you know for a fact the recipient is good at context management) yet it is far more efficient to write three emails and get a congruent response to each than to write one email followed by a chain of a dozen follow ups that may or may not conclude in everything being answered.
I feel so strongly about this, I wrote a longer rant recommending to Keep Emails to a Single Topic a year ago.
Even congruent email chains can move from one topic to another. If you are the one writing the email with a topic change, change the subject in the email, even if you do retain the earlier thread as a related reference. If someone else changes the topic, update the subject in your reply with [New Subject] (was re:[Old Subject]. When you go to search your email for a thread several weeks later, you will be glad you did.
When replying to an email where many people are on the thread, remove the list of recipients from the original email, especially when updates are inline (another bad practice).
Many more tips to come…
Some tips from a previous page on this blog about meetings…
One type of meeting is for the purpose of people with something in common (a project, a department, a role, a skill set, an interest, etc.) to gather and have a free form exchange of ideas. These types of meetings need only a clear topic and basic shared ground rules (at a minimum, always be respectful) to be productive.
The other type is to accomplish one or more specific goals. If there are more than three goals, some will be missed (and some can still be missed with only three). These types of meetings require a specific agenda beyond the meeting topic. They require that someone is recognized by all as the leader or facilitator or moderator and that person knows how to perform in that role. They require someone good at note taking to be the scribe (or a method of recording the meeting on a shareable medium). If the meeting is missing any of things, any successful outcomes are the result of luck or the meeting was really one of the first type.
It is a good habit to record the web conferences you host and request other hosts to record and post the recordings for participants. This allows you to focus more on the meeting rather than taking notes. It also provides a reliable source of reference when different attendees later have varying recollections of statements and decisions made in meetings.
The project retrospective is a chance to commit the lessons learned to memory. The issues with retrospectives come in bookend-form: It takes a long time to get the creativity and honesty flowing at the start of the retrospective and the captured lessons are rarely referenced by anyone not in the meeting. For the latter, you can blog about the lessons you’ve learned and for the former you can come prepared (you’d be surprised how often you are the only one).
To be prepared, it is best to keep running notes throughout the project (I use Evernote) or at least to put together some thoughts at least a day in advance of the meeting. If you are the only person that does this you can single-handedly knock over that first bookend (just like that couple that would always be the first to dance in school).
I strongly suggest that you have as many positive items available as possible so that you are ready to start it off on a good note. If you have several, space them out if others do not
Another approach that I have found to be successful may seem counter-intuitive: Make your first “area for improvement” shared something that you were responsible for. This is especially important if you are the first to provide it because by honestly recognizing and sharing your own contribution to things that went wrong it will ease the concern others have of being picked on. The group will be more relaxed and open up sooner, making the meeting highly productive.
I can’t find a solid attribution to the title of this post, I only know it isn’t me. But I wish it were. I read it first in a Tom Clancy novel and they were talking about the stock market. I don’t say it nearly enough, and I’m talking about IT documentation.
Say what you want about “self-documenting”. Until that becomes a solid feature of an “AI” product, self-documenting isn’t. If you don’t believe me, find some code or configuration file you wrote 3 years ago and haven’t looked at since and tell me what it does and why. Yes, there will be a small percentage of cases where this will be perfectly clear, and to those few I say “now hand it to someone you have never met and see if they get the same information””. That percentage drops drastically.
Here are some of my thoughts on documentation that I hope will inspire you to create more and help you to make it as useful as possible with the least effort necessary.
Customers often do not look for documentation gaps until near the time when they expect them to be completed. Ask for their specific documentation requirements up front. They may later want to expand that list, and acquiring the list at the beginning and publishing the list for customer review early in the project will allow for better prioritization when the project is nearing the end.
Many initially successful projects can later be viewed as poorly delivered when proper documentation for enhancements and maintenance is incomplete or non-existent. Begin your documentation as early as possible with a full outline and then fill it in the details as time permits. This helps to reduce the project wrap-up stress in starting documentation from scratch at the 11th hours.
Templates help to standardize documents for easier reference and provide reminders of sections to include and approaches for presenting specific topics.
While it is tempting to start from an existing document, this can result in bad data being left in and verifications of details between designs being properly verified. One example is a project that had scheduled jobs that ended up overlapping because the team kept creating new documents from the existing documents and leaving the schedule table unverified.
There are few things more frustrating to someone trying to accomplish a specific task according to instructions to get stuck because their current results don’t match the instructions. Who they blame for this is often more of a reflection on their temperament than the instructions, and in IT it is fair to say that most of the time it is the fault of the instruction. Other than true technical writers (there are many in tech writing roles who are really either copywriters or editors and not true technical writers), most people who write documentation do so from the perspective of having already accomplished the task. While being able to do the task can be very useful in writing documentation, knowing how to look at the task through the eyes of someone who does not is the key to being a good technical writer. Follow the steps of your own documentation exactly from the point of view of having never done it before (VMs are great for this), and revise your documentation every time you find a missing step or a concept that is only clear with experience of having already accomplished the step or task. If you have a hard time doing that, have people with no understanding of your subject follow your documentation (without you present!) and provide feedback.
Unspecified nouns are words such as this, that, they, and it. The use of unspecified nouns can be confusing if there is more than one possible interpretation. While you, as the communicator, may only see one meaning for what is referred to by the unspecified noun, a reader or listener may not.
For example, “they may not understand the purpose of the link” is clearer as “stakeholders may not understand the purpose of the link” or “users may not understand the purpose of the link”, both of which may have different meanings.
While it may seem excessive and repetitive to do so, repeat the name of the thing you are talking about rather than assuming that everyone will know what this is meant by that.
Note, this has nothing to do with use of preferred pronouns. I was using they and them for years and wish I had contact information for the teachers and editors who kept insisting I use he and his when referring to an unspecified actor or reader so I could send them an I-told-you-so emoji.
The value of a guide is that people should be able to use the guide to complete the tasks it describes without assistance. First validate it yourself by following your document exactly as you have written it. Then have someone that will be a consumer of the document go through and follow the guide, having them make notes with Track Changes turned on. Bonus points for getting someone that has little understanding of the supporting technologies to do the validation.
Screen shots should be used when they enhance understanding, allowing fewer words to describe the full details. They are not a replacement for all descriptions. At a minimum they should have a caption.
When values need to be entered in a screen shot, always include the values as text so that readers can copy/paste the values. Command line entries should use a style indicating they are commands rather than a screen shot showing the command, again to facilitate copy/paste and also because:
Is not clearer than:
Type this here
Throughout the project you will need to find information online relevant to the solution. In addition to maintaining your own reference bookmarks, whenever you find a URL particularly useful to the solution add it to the Reference Links section of the project documentation. If you do not own the document, send the links to the team member that does for inclusion.
Hopefully your employer and/or client have a Knowledge Management system. At a minimum, the following milestones should be a reminder to contribute to this shared knowledge base:
If you find it difficult to remember to make KM contributions following these events, set a regular reminder (weekly if not daily) to think about your activities and accomplishments and if there is something that is worth sharing, then do so.
If there is to be performance testing both the test tool platform and the test environment need to be robust enough to support it. This will require either a server farm capable of exercising the application at a realistic load or ensuring that the application performance test interfaces can be accessed by an external cloud-based platform. In the latter case, plan security testing to be done before the performance testing.
Many projects do not use automated testing because of the time involved in creating the tests. This is based on optimistic estimates of expected number of defects and iterations to resolve. Ironically, not having automated testing for regression testing increases the number of iterations to resolve defects and increases the total effort of testing.
Acceptance tests are generally limited in scope to how users are expected to use the system. Regression tests should include edge cases and dynamically-generated inputs, with the inputs recorded in the event of defects being identified in order to support re-creation and potential adjustments to test parameters.
Defect summaries should be formatted as TYPE: Component – Functional Error Summary
