{"id":24013,"date":"2021-08-16T16:11:14","date_gmt":"2021-08-16T23:11:14","guid":{"rendered":"https:\/\/www.podfeet.com\/blog\/?p=24013"},"modified":"2021-08-16T16:11:56","modified_gmt":"2021-08-16T23:11:56","slug":"non-realtime-communication-at-work","status":"publish","type":"post","link":"https:\/\/www.podfeet.com\/blog\/2021\/08\/non-realtime-communication-at-work\/","title":{"rendered":"Non-realtime Communication at Work \u2013\u00a0by Allister Jenks"},"content":{"rendered":"

Back in March I took part in CCATP Lite #675<\/a> about working from home, along with Allison and the pod-daughter, Lindsay Tondee. We had so much fun discussing our different experiences that there was a whole section of content I had notes for that we just didn\u2019t have time to get into. I\u2019d like to cover that now. The topic is non-real-time communication.<\/p>\n

I think I mentioned in CCATP that one of my driving forces for the way I work is being lazy at heart. If I can save people having to bother me, I\u2019ll put in the work ahead of time to ensure it is so. Occasionally I have the opportunity to teach, which is something I really enjoy, but more often there is simply not time, or sometimes no inclination, to properly teach a topic. At these times I turn to the next best thing \u2014 documentation.<\/p>\n

I used to have an attitude common amongst technical staff \u2014 \u201cI can either document it, or do it.\u201d Two events happened that turned me away from that way of thinking, and they happened in the same job and a couple of years apart.<\/p>\n

It was 1998 and I was working for a large multinational company with my chief focus at the time being the introduction of a new software tool into our development team. When I say it was my focus, I mean it was my responsibility<\/em>. I and my team had put a lot of work into figuring out configurations, extra tooling, processes, and more, and we were piloting the results with one project within the development team.<\/p>\n

\"MicrosoftThings were moving fast. Things were breaking. Despite some initial training, developers and testers alike had lots<\/em> of questions. We noticed the same questions being asked over and over so we started writing an FAQ. This had a positive effect but still people would turn up at our desks, FAQ in hand, seeking clarification or the answer to something not in the FAQ. We constantly refined that FAQ to address more and more of what people were struggling with. It started getting big, but it was working. Or was it?<\/p>\n

One day, just after a developer had left my colleague\u2019s desk, FAQ in hand, he turned to me and asked \u201cDid you see that?\u201d My puzzled look prompted him to expand. \u201cHis FAQ was a really old version!\u201d We\u2019d built our FAQ in Microsoft Word and we made sure to put the date of last update clearly on the document, but the nature of such documents is they get passed around from person to person and, worse, printed.<\/p>\n

Not getting the document from source is a problem, but printed documents are worse. They are quick to reference, but are out of date as soon as the toner hits the paper. It didn\u2019t matter that the date was there on the front page, because the front page was folded behind the rest as it sat on all those desks. Our constant work to revise and expand the FAQ was somewhat in vain. We needed to address this problem \u2014 for the benefit of the development staff, but also for our own sanity.<\/p>\n

\"LotusThe company had recently rolled out Lotus Notes and we realised it would solve the problem. We built a Notes database which was a simple, categorised list of questions. When the user clicked on a question, the answer would be revealed. We had essentially the same capabilities as Word, including screenshots and marking up standard terms, code, commands, and more to aid in legibility. We quickly converted the contents of the Word document into the database and then went around everyone\u2019s desks confiscating their printed copies as we explained the new tool and showed them how to use it. Our support burden went down literally overnight. Everyone had easy access to the latest information with a few clicks.<\/p>\n

This lesson didn\u2019t really sink in for me until the next event occurred two years later. I had been a self-employed contractor at the company for four years but management were souring on this long-term contracting concept and I was tipped off one day that my own job had been posted on the company job board as a vacancy! I applied and, astonishingly, I got the job. My job. I was now a permanent employee.<\/p>\n

Not much changed on a day-to-day basis, but there were certain requirements as an employee, one of which was that I have my Personal Business Commitments formalised and on record. (Anyone who worked at the same company is now sure they know who I worked for.) I sat down with my boss, who I knew well, to discuss these and I cheekily offered this appraisal: \u201cLet me guess. My commitments are your commitments and yours are your boss\u2019s and theirs are their boss\u2019s and so on, and none of it means much except \u2018do what you\u2019re told.\u2019\u201d Without a flicker of emotion he replied: \u201cEssentially yes, but I\u2019m adding an extra one just for you.\u201d<\/p>\n

His new commitment for me was very simply expressed. \u201cReduce the team\u2019s reliance on you being here.\u201d I was, by that point, the senior member in my team \u2014 mostly through attrition \u2014 and had recently been overseas for several weeks at a time, working at other company sites. I asked how he thought I was going to achieve that and his reply was equally simple. \u201cI don\u2019t know but you\u2019ll have to work something out.\u201d Spoiler alert. I did.<\/p>\n

It didn\u2019t take me long to figure out that our pilot FAQ held the answer. Not literally, but in its very existence. What if we had a team FAQ as well? A place where the whole team could distill their knowledge in such a way that it became every other team member\u2019s knowledge as required. The pilot FAQ had since become a \u2018production\u2019 FAQ as we had rolled out the database to everyone, and it had grown a lot. As such, I found it a bit unwieldy, so I set about building the team FAQ a little differently.<\/p>\n

I discovered with a little tinkering, that a Lotus Notes database could act like a web site. I built out a front page with links to a series of categories, each of those being a page of its own and each containing links to further pages with the actual content. The real power came in those content pages where further links could be included to related pages. From this I developed a simple approach to writing documentation most efficiently. That is, efficient to write and efficient to use.<\/p>\n

These were my rules:<\/p>\n

Never write anything in more than one place.<\/em> If you had to do process A before process B, then the process B page should mention this fact and contain a link to the process A page and not a duplication of the same steps, no matter how simple process A was. This meant if process A ever changed, it only needed to be updated in one place. For simpler processes that are used in a lot of places, this saves an enormous maintenance burden.<\/p>\n

Write for the correct audience.<\/em> While our project FAQ had addressed an audience of developers and testers, our own team database \u2014 which we called the Team Knowledge base \u2014 could be a lot more technical at the operating system level, and could assume certain knowledge that developers and testers would not have. Writing for the correct audience is most efficient.<\/p>\n

Use numbered steps for processes, but not ONLY numbered steps.<\/em> Numbered steps are incredibly useful for following an unfamiliar or complex process, but those steps should not be a simple sentence or command. They should spell out exactly what to do. And they should follow the next rule.<\/p>\n

Always explain WHY.<\/em> Have you ever tried to follow a process only to find out part way through that something it said would happen didn\u2019t happen, and now you\u2019re stuck? I have, and it can be infuriating. If the process explains at each step why<\/em> you should do what it says, then you have a fighting chance to work out what is different and proceed with the rest of the process.<\/p>\n

Test the process.<\/em> A process is only of any value if it works, and that means it needs testing. You can run through the process yourself but the ultimate test is to get someone else to do it. Preferably someone who doesn\u2019t know much about the topic. There was one memorable process in our knowledge base which showed the power of testing. One member of my team had developed a very complex process which no-one else in the team had any idea how to do. Including me. I pressed him to write up a process but he was extremely busy. I eventually got a rudimentary process out of him and then asked a whole bunch of questions. From this I wrote up what I thought was a proper version of the process. On my first test I failed dismally. More questions ensued until I finally thought I had a handle on it and I updated the process to what I thought must be near complete. I then handed it to another team member and asked them to have a go. More questions, more updates and they got through the process. Then I handed it to yet another team member. There were seven members in my team including me, so that\u2019s five people not originally involved in writing up the process. I gave it to every single one of them to run through a real task and the fifth and final person gave me back the printed copy I had given them (there was no access to the electronic version where it needed to be used) with a single markup in red pen where something I had said would appear was not shown correctly.<\/p>\n

And the final rule, if you see an error, correct it<\/em>. Updating the process during the testing phase is vitally important, but that should not be the end of updates. Processes, tools, requirements, and more all change over time. Sometimes even the most comprehensive testing can still miss things. This final rule is what stops the knowledge from becoming obsolete. It\u2019s also the rule that keeps people using the resource. It doesn\u2019t take long for someone who keeps finding the information wanting to stop using it altogether. Conversely, I have found that keeping things fresh not only ensures consistent use of the resource, it also encourages others to make their own updates when they see issues.<\/p>\n

There is one other thing I didn\u2019t make a rule but which is definitely worth considering. A common phrase is \u201cDon\u2019t let perfect be the enemy of good.\u201d The example I described above was certainly the only<\/em> process in our knowledge base that got that level of testing. Some processes weren\u2019t everything they could be, but they all worked<\/em>. There is also a saying \u201cSomething is better than nothing.\u201d There is value in a \u201cknowledge dump\u201d \u2014 where someone quickly pastes in some notes with the intention of later fleshing it out into something more useful.<\/p>\n

Everything I have described has focused on processes\u00a0<\/em>but there is another class of information which should sit right alongside these. The team knowledge base I built formalised the two types as \u201cProcess\u201d and \u201cReference\u201d pages. Reference pages did not describe how to do a task but rather how a particular tool or technology worked, how it was configured in our business, or a list of tips and techniques. These reference pages were often linked to from process pages and vice versa. This was a big help with the why<\/em>\u00a0rule in process pages, and when looking at a \u201chow it works\u201d reference page you could quickly go to related processes to see how it was used.<\/p>\n

A year after that sit down with my boss, he agreed I had achieved my objective. I had absolutely reduced my team\u2019s reliance on me being there, and this was illustrated perfectly with another overseas trip I did a few months later. Upon my return, I asked one of my team members \u2014 my official stand-in while I was away \u2014 how things had been in the three weeks I was gone. His response was \u201cAll fine, but we weren\u2019t sure about this\u2026\u201d They had kept one single issue for me to address when I returned. And it wasn\u2019t anything urgent or terribly important.<\/p>\n

\"MicrosoftI have since built, deployed, and championed knowledge bases in two subsequent roles and my team today is fully on board with what we call our wiki. Though originally built with wiki software it now resides in Microsoft OneNote which, like Lotus Notes, allows a locally stored and regularly synced copy. It also has a very useful feature in that it highlights pages that have changed since you last visited them. This enables me to see just how many updates my colleagues are making. It\u2019s sometimes hard to keep up.<\/p>\n

The real value in our \u201cwiki\u201d is realised when team member who is on call gets roused at 2am on a Sunday for an issue, and effectively has the entire team\u2019s expertise on hand to help resolve it. Often during work hours one of us will utter the phrase \u201cput it in the wiki\u201d when something is discovered that isn\u2019t already covered and every time it appears there in short order.<\/p>\n

I have come across people during my career who think this free giving of knowledge is a bad thing. They believe that holding the knowledge makes them indispensable. I have also seen that this is simply not true. When it comes to downsizing, rightsizing, restructures, or whatever you want to call it, held knowledge doesn\u2019t seem to be a huge factor. Instead, people who have experience<\/em>\u00a0are valued more if they willingly share it. Despite my earlier comment about laziness, it can actually be hard work to create good documentation but I believe that sharing information gives everyone the best outcomes. Information you impart freely will unburden you from being \u201cthe expert\u201d all the time and if everyone pitches in \u2014 the whole becomes greater than the sum of the parts.<\/p>\n","protected":false},"excerpt":{"rendered":"

Back in March I took part in CCATP Lite #675 about working from home, along with Allison and the pod-daughter, Lindsay Tondee. We had so much fun discussing our different experiences that there was a whole section of content I had notes for that we just didn\u2019t have time to get into. I\u2019d like to […]<\/p>\n","protected":false},"author":29,"featured_media":24015,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[147],"tags":[2458,1166,4684,233,398,4685,3632,4687,4686],"class_list":["post-24013","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-posts","tag-communication","tag-documentation","tag-lotus-notes","tag-microsoft","tag-office","tag-onenote","tag-process","tag-reference","tag-wiki"],"jetpack_featured_media_url":"https:\/\/www.podfeet.com\/blog\/wp-content\/uploads\/2021\/07\/OneNote.png","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/24013","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/users\/29"}],"replies":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/comments?post=24013"}],"version-history":[{"count":5,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/24013\/revisions"}],"predecessor-version":[{"id":24240,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/24013\/revisions\/24240"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/media\/24015"}],"wp:attachment":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/media?parent=24013"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/categories?post=24013"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/tags?post=24013"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}