Zen and the art of IT Consulting Archives - Page 2 of 3

Written Instructions image by https://www.pexels.com/@markus-winkler-1430818/

Document Like You Don’t Know the Subject

June 30, 2023July 7, 2023Scott S NelsonLeave a comment

(Feature image credit: Markus Winkler)

“All books are just the same letters in a different order”. -Unknown

I know I originally heard this (paraphrased) quote from a comedian. I thought it was Stephen Wright, though I was unable to find this attributed to any comedian on Google. The closest attribution I could find is to the author Cornelia Funke: https://quotefancy.com/quote/1197597/Cornelia-Funke-Weren-t-all-books-ultimately-related-After-all-the-same-letters-filled.

Point being (my regular reader knows I wander off point often, and hopefully entertainingly so), I think that many people tasked with writing documentation think that all the information is right where they found it, and that anyone else can do the same research and come up with the same understanding. To counter that view, I point you to the news and whatever thing people are doing or saying in large enough numbers to be noticed while the vast majority realize that nothing could be further from the truth.

The thing about documentation, the numbers are generally the opposite, in that only a few understand the need to be specific, explicit, and concise.

The trick that has always worked for me is to write the content, then follow the content as if I had no previous understanding of the topic.

When possible, I prefer to go one better and find someone who really does have no understanding and ask them to follow the content. My greatest success with that method is when I created a 20-page document (with lots of screenshots) that walked developers through the sequence of steps to become productive in working with an enterprise J2EE application with authentication and external system integration. The goal was for new developers to complete the process in under 30 minutes with no assistance. My final test of the documentation was when I gave it to our visual designer who completed the process in 40 minutes with no help other than the document.

At the least, I always try to get at least one consumer of the documentation to go through it and provide feedback. When possible, publish the documentation to a platform that encourages feedback. Even better if peers are allowed to edit and revise on their own.

Finally, when comments are edits are made, it is best if the platform provides an alert mechanism so that the content owner can review the changes or comments.

One way to keep documentation fresh

June 29, 2023July 14, 2023Scott S NelsonLeave a comment

Documentation should always have some built-in capability to receive comments and the comments should generate alerts to the content owners.

This process can vary greatly. In some contexts, readers can be allowed to edit the content. Or only some users. Those edits should still trigger alerts to the content owners for review.

Documentation often becomes stale because there is no easy way to communicate changes. Capturing improvements or updates at the time the document is used is the next best thing from when the content needs revision because what it describes has changed.

Bonus approach

For software documentation (especially for enterprise applications), if you use any kind of ticketing or kanban-style stories, include “Create/Revise Documentation” as a standard part of the Acceptance Criteria in your template.

Email Best Practices

April 10, 2023November 18, 2023Scott S NelsonLeave a comment

There should be books written on this topic. Many, and all with fewer than four paragraphs or no one will finish them.

Manage email subjects

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:

Keep the email to a single topic

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.

When the thread changes topic, change the subject.

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.

Trim to fit

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…

#TIL: How to Present PowerPoint Slide Show in a Resizable Window

September 1, 2022October 21, 2022Scott S NelsonLeave a comment

Full screen is great if you don’t need notes. Until today, if I need notes I just minimized the tools and gutter while presenting. And then I discovered this:

Slide Show > Set Up Slide Show > Browsed by an individual (window)

My Pinned Wiki Post Template

July 21, 2022October 23, 2023Scott S NelsonLeave a comment

If you use this, please link to this blog post.

This is our Wiki

There are many like it, but this one is ours.

Our wiki is our guide. We support our wiki through comments and additions.

Without updates, our wiki will become outdated. Team members will become frustrated when information is missing or no longer correct. Being a good team member includes being a contributor to the wiki.

That cool reference you found that you will always remember? One day, when you need it most, you will forget it.

That awesome solution to a code or design issue that is perfectly clear and understandable now will look like a foreign language in 2 years (months, weeks, sometimes even hours). Add an explanation to the wiki.

When in doubt if something should be added to the wiki, add it. It can always be deleted later.

This is your wiki. Keep it clean but not too lean.

The Architect
(A serious parody of The Rifleman’s Creed )

(“Obligatory WIki Photo” by cogdogblog is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/?ref=openverse.)