Imitation is the sincerest form of flattery

I am a firm believer of solving a problem and sharing it with your peers.  All code construction can do with a second set of ideas/eyes or a different perspective.  Those that 'care to share' will also learn as much as those you intended to educate.  Simple Truth.....Those that don't share are NOT as good as they think they are.....

Why? 

Quite simply... It is about creating a culture within your team that empowers the individuals for the greater good of the team

Having someone copy your code is a compliment, take it that way, but remember you can also be productive and actually.....  Share it ........

Today I wanted to debate the issues of cloning and blatant stealing of games and applications on the relevant app stores.  Whether you are a hardcore iOS lover or a thrifty Android devotee you will all have come across apps that have been cloned.

Anyone remember Flappy Bird?  There were hundreds of copycat games that used some of your valuable storage.  These clones whilst annoying are an inevitable occurrence if a gravy train/gold rush is created.  And we have certainly seen out fair share of these in the main app stores.

A few years before this we had xxxxxx Birds or Angry xxxxxxx clones and this continues today with 2048, Wordscape.........

Guess what?  It even happens for blogs......

I have discovered in recent weeks/months that someone has cloned my entire blog.  Probably not for any other purposes that trying to divert traffic to their sites.... (I'm sure they'll be happy with a few hundred extra page impressions (a month).

Remember: My blog has my name in the URL.....and oh, yes I am flattered.......

Thanks for reading.

Lee.

Consumer or Contributor?

Originally written in March 2018 but never published as I never left....... Now that I have it felt right to post it...

Are you Contributor or Consumer?

I have today finished working for my current company in NZ.  I have dozens of reasons why I chose to leave so I will only put out a few.

• I wanted a new challenge.
• My career was going backwards due to numerous structural changes and then outsourcing.
• Same old approach, same old processes that were as sacrosanct as a religious text with no hope of change.
• I realise that there is so much more (good tech) out there than the bubble we’d been enshrined in and due to our skills rarity.
• Promotions were literally waiting for incumbents in the senior roles to die or retire (Lessened with outsource)
• Desire to chase my own dreams.....while I still can.

Another Issue

Sadly, another issue was that I realised I had become surrounded by more consumers than contributors.  This can be true for many teams and companies and is not unique to the team above. 

In my years back in the business it became obvious that many of the developers were consuming my knowledge (I like sharing), but, at the same time, some were opposed to sharing theirs.  There were a few good eggs though and you know who you are :-)

Which type are you?

There are two types of developers in this world. Those that ‘learn/implement/teach and share’.  And then there are those that learn solely to strengthen their individual position, or in this case (at this firm), their collective position.  Some go as far as making areas of expertise for themselves in a vain attempt to make themselves indispensable, not realising that this selfishness was actually harming the growth of the business and stalled their own career.

I've known of developers with 25+ years’ experience in the tools that had never even posted a blog or a forum answer on 2E or Plex.  Their interest in the tools (and tech) was only deep enough to grow their individual product (business) knowledge.  They’d never given back to the wider community, they had only even dined at the free buffet of knowledge.

I had questions in my mind......

• Who are these people?   
• Why was I wasting my time trying to help change this culture? 
• Perhaps it doesn’t need changing?
• Perhaps the problem is me!

In life we choose our friends and they choose us.  With school and work especially, we are often forced together....

Personal Impact

I had let myself get so despondent about this scenario that I know that even if I went for another job right now, my frustration would be etched across my face and it would do me little good.  I place no blame at the feet of the outsource provider through which I was working via....The damage was already done before that deal was struck.

What Next?

I’m not driven by money, power or job title (so many managers have failed to understand this part of my personality) and suffice to say, I will have many options so I am looking forward to finding my happy place.

Now is the time to take a break, recharge my physical and mental batteries and then look for a future challenge or focus full time on my dreams…..

My biggest takeout is, if you have tried your best to improve the environment around you but see no signs of it improving, walk away.  Some places/teams/processes are just broken, channel the energy somewhere that warrants your investment/time... including you.


Look after yourself and live your dreams.....One life.....

Thanks for reading.
Lee.

p.s. When I got home and told the trouble and strife (wife) that I have resigned.  She said it's the first time she had seen me smiling for a while...... I reckon I made the right call, just in time.

p.p.s. If you find that you are a non-selfish consumer.  i.e. someone who is absorbing the knowledge at present but don't have a forum to pass on your knowledge, that is fine.  Just remember to not become one of the selfish hoarders when your time comes to share your knowledge...

Knowledge capture & use in technical support communities - Part 3

In Part 2 I looked at how to capture expert knowledge. In this final instalment, I will offer suggestions on where to store that knowledge, some differing uses of these concepts and offer some final insights into why I wrote the original version of this article.

Once again, I lead off with a small overlap to set the scene.

Electronic storage for fast access

Following the structuring process above introduces one significant disadvantage in a paper-based documentation repository. Frequent referencing to other documents causes the reader to flip pages or have multiple documents arranged on the desk in order to complete a single process.

Simply storing these documents electronically, such as Microsoft Word files in a LAN folder, is not enough to deal with this problem, as it merely shifts the emphasis to clicking the mouse constantly and still does not help out with the comprehension of the process as a whole.

The answer is hyper-linking. Every single reference to another document should be turned into a hyper-link to that document. This guarantees simple, fast, unfettered access to the linked information and, in most cases, an easy return path to the original document.

It is important to choose the document delivery technology with this method of usage in mind. Although MS Word provides inter-document hyper-linking capabilities and is an excellent document editor, it leaves a lot to be desired as a document reader. Better choices are Lotus Notes, or HTML. Lotus Notes serves as both editor and fast viewer. HTML requires a separate editor (and there are many to choose from), but has a ubiquitous interface if you are considering a large audience for the documentation.

Although I would recommend Lotus Notes as an excellent delivery mechanism, it is important to avoid the use of Notes 'Views'. Rather a default, or 'home', document should be launched easily from a bookmark and all navigation from that point should be via hyper-linking. This gives immediacy to the navigation by making it all point-and-click. This typically avoids the need to work with Notes' view characteristics like 'twisties' and scrolling. (Note that both of these can be used within a Notes document if desired.)

Tech-centric versus customer-centric

At the beginning of this series, I referred to the workings of a technical support team. For such a team, there are two key audiences for a documentation repository following the guidelines described in this document.

Perhaps the most important audience, in terms of covering exposure, is the team itself. Sharing the expert knowledge around the team ensures that individual team members do not become indispensable.

However, often the single biggest gain to be made from good documentation is by providing the team's customers with 'self help' information. The audience level for such documentation will necessarily be much lower than for internal documentation and will therefore take more time to prepare, but the ability to point customers to a self-help document for a common problem can save the team enormous amounts of time. This time could be used to improve the internal documentation and then you can reap all of the benefits.

The author's experience

In writing these articles, I am speaking from experience. I have built a customer-centric and a tech-centric database along these lines and they have been very successful. Both were built as Lotus Notes databases.

The first one built was the customer-centric repository, which was deployed to up to 150 developers and testers. This originally came out of a FAQ document introduced during a pilot implementation of a source configuration management product. The documents were listed in a Notes view in broad, simple categories. Each document title was phrased as a question, the answer to which lay inside. Many of the documents referred to others for pre-requisite information.

My team used this database to help keep the load down in our helpdesk-like operation. I estimate that once the database had matured, over 90% of customers who were referred to one of the documents did not need to make further contact with us for that issue. It is clear from the numbers and the nature of calls we received that many customers went straight to this repository and never needed to call us.

The second database was tech-centric and used all of the principles described above. Although the closure of the business meant this repository never quite made it to 'complete' status, the documents that were created (over 60) proved the points I have made above. New members in the team who were technically competent (that's why we hired them) but who had scant knowledge of our processes were able to perform fairly complex tasks purely from the information contained in these documents. Although it took them sometimes magnitudes longer to perform the task than one of the experts, the fact remains that they successfully completed the task with low or no input from the experts in person.

Reflection

In the matter of conversational language being more effective than rote instructions, I can recall being given two articles to read in preparation for a 'knowledge workshop' (that unfortunately never happened).

After many years now, I can only remember what one of those documents said. The one I remember spoke about how conversational language was much more effective than brief and often brusque language that is found in much technical documentation. It made the link to the over-the-shoulder technique and postulated some of the thinking that I have expounded above.

Some time well after I had created the customer-centric database I came across these two documents and re-read them. I immediately tied the conversational language ideas to what had happened in our database and saw that it was true. After re-reading the documents, I also realised why I had remembered this document and not the other. This one was very conversational, in contrast to the much more formal (and fact-and-figure quoting) style in the other document.

To this day, I do not remember what the other document said. Perhaps sometime I will come across the pair again and the cycle will repeat.

Thanks for reading.
Allister.

Knowledge capture & use in technical support communities - Part 2

In Part 1 I discussed the problems facing the technical support team with overworked experts and a need to transfer their knowledge as efficiently as possible.

In Part 2 I will discuss how to successfully capture and store this knowledge in an efficient and, above all, useful way. I'll lead off with a brief overlap from last time as a reminder of where we got to.

The 'Virtual Expert'

From what has been discussed so far, it is clear that expert knowledge is required, but that tying up the expert in this process is seen as unproductive in the current climate. We cannot get away from requiring time from the expert, but we can minimise this time and capitilise on it by recording the knowledge in the right way.

The answer lies in recording the expert knowledge (on paper or, more usefully, electronically - see later) in such a way that it is as close as possible to the over-the-shoulder commentary.

There is often still a need to use numbered steps when accomplishing a task. Such steps provide structure and sequence and help with mental tracking when performing the task. There is no reason, however, why each step cannot contain more than simple 'input, output' or 'action, reaction' type information.

For maximum benefit, each step should be written in conversational language and explain what the user is doing, why they are doing it, what the expected outcome should be and at least make reference to any unusual, but known, variations.

Furthermore, before any of the steps, there should be an introductory section which describes why the user would perform the task, what pre-requisites there may be and definitions of terms, systems and the like. After the final step, make mention of any further tasks that may be a logical progression from the task described, but which do not form part of this process.

Don't take anything for granted

Whilst we are talking about capturing expert knowledge, it is important not to lose sight of the basics. Any documentation is devalued if it makes too many assumptions. In creating a documentation repository, an audience level should be decided - such as 'technically competent', or 'beginner' - and all documents should be written for that lowest common denominator. It is easier for a more expert user to skim over known material than it can be for a new person to work out the undocumented basics.

It is important to include examples in the documentation. Where possible, have the example show the most common scenario, as it is most likely that staff new to the task will use the examples. It is also worth giving additional examples if there are significant variations in a step. Providing examples helps the user to get closer to the over-the-shoulder situation.

The ultimate test for the documentation is to give the process to a person who is at this 'lowest level' and have them perform the task. You will be surprised by some of the information you have taken for granted in your early drafts. I know I was.

Structuring the documentation

For ease of maintenance, it is important to only ever store a piece of information in one place. To help achieve this structure, it is useful to allow for two document types in the repository - reference documents and process documents.

Process documents contain steps describing how to perform a task. Reference documents contain (mostly-) static information that supports one or more processes.

It is often necessary to refer to tables of information (such as a list of files, describing their usage) from more than one process document. By separating this type of information into a reference document, it can be referred to by multiple process documents without increasing the maintenance burden through multiple copies. Additionally, when the table requires maintenance, it is easier to locate (residing under its own title) and the maintenance can be performed without danger of corrupting the process documents. When properly structured, maintenance of the reference document can be accomplished without knowledge of the referring process documents.

Whilst reference documents tend to represent pure data, it is still important to keep the conversational language in mind. There may be naming conventions or other conventions which are being followed for the data and it is important to note this in the reference document to complete the picture for the user of the information, and equally importantly for the maintainer.

It is also beneficial to factor out sub-processes into separate process documents and refer to them from the major process documents. This is of value where a sub-process is part of more than one major process.

The major benefit of having information in only one place is realised when errors are amended or updates are applied. These have to be done in only one location and all related processes are automatically catered for, as they simply reference to this single occurrence.

Capturing is understanding

The process of capturing information is time consuming and is best not left to the individual experts. Remember that they don't have that much time. Also, too many authors can devalue the repository by differing styles and levels of language.

The best solution to this is to have a single person (or possibly two or three) to build the documentation repository. This co-ordinator is then responsible for collation, setting style and keeping the language consistent. This person should not be expected to author all of the documents, but must be able to understand at least the broad concepts involved in order to ensure that appropriate structure is followed.

Each expert should be expected to provide a draft of the process or reference data, in a form approaching the final requirement. In some cases, where the co-ordinator's knowledge is good enough, they may author the document, but it should always be checked by the relevant expert.

Electronic storage for fast access

Following the structuring process above introduces one significant disadvantage in a paper-based documentation repository. Frequent referencing to other documents causes the reader to flip pages or have multiple documents arranged on the desk in order to complete a single process.

In Part 3, I will discuss some real world solutions to electronically storing, maintaining and delivering the captured knowledge.

Thanks for reading.
Allister.

Knowledge capture & use in technical support communities - Part 1

This three-part article is adapted from one I wrote almost 5 years ago when much of what you will read about was fresh in my mind. This adaptation addresses only the passage of time and some points of style and meaning for a wide audience.

Whilst software development is the subject of this blog, let us not forget those who (typically in large organisations) support the developers and others.

The nature of technical support communities.

Technical communities come in many forms, be they design teams, development teams or support teams.

Whilst design and development teams are largely about the creation process, they still have many day-to-day activities which are defined and repeatable. Support teams, although fulfilling an entirely different role, often have to create on a very short-term basis. So it can be seen that the different types of teams have similar requirements.

However, the support team seems, most often, to be the one to get out of control. The difference is that the support team is always working on a short time frame. In addition, support teams often become involved in project work and this adds to the complexity of the day-to-day activities, as the time frames are shortened still more.

Most often, you will find that staff in a support team are very good at what they do - they have to be to survive. Unfortunately, the higher the skill of the staff, the more reliant you are on those staff to keep the systems running. It is a difficult and time-consuming option to bring 'green' members into the team.

How many support managers have not recognised that documentation is a key part to the support process? I would wager very few. Fewer still, I propose, have succeeded in completing the documentation requirements within their team and reaped the kinds of benefits they were expecting.

Documentation, to the 'tech', is a four-letter word. I, myself, recall asking the question "Do you want me to document it, or do it?" Simple economies prevent the techs from having enough time to complete the documentation task and many welcome this excuse not to do it.

Another trait of support teams is the experts. In virtually any support team, there will be experts in various disciplines. Most often, however, these experts are relied upon to provide most of the resource in fixing problems in their area of expertise when they should, in fact, be called upon to share their knowledge.

Shared knowledge is a powerful tool. Experts will always be needed when particularly difficult or unusual situations occur, but the team as a whole should be able to leverage the experience to improve task turnaround times through a more even spread of the load.

Knowledge transfer

It has been documented in studies that the best way to learn something is to have an expert stand over your shoulder while you go 'hands on'. The reality of the situation in front of the learner, coupled with specific and pertinent comments or instructions from the expert gives the learner an experience often indistinguishable from the real thing. The learner also has the opportunity to ask direct questions in the context of what they are doing. Book learning, on the other hand, can only go so far with static examples and predetermined situations.

Perhaps the most important aspect of 'over-the-shoulder' learning, however, is that the expert is unlikely to simply recite steps by rote. There will be an accompanying commentary and usually a significant amount of reasoning on why things are done that way. This is very important in equipping the learner for when things do not go to plan.

Learning the steps of a process by heart is well and good when the process works. Most often, however, processes do not cover all possibilities and the rote-learner of the steps is going to come unstuck when an unforeseen, or simply undocumented situation arises. Unless the learner understands why they are taking the steps and what they should be achieving, they are almost as much 'in the dark' as prior to learning the steps.

Having knowledge about the nature of the process and the goings on under the covers helps get through many small deviations from the norm and also helps in issue resolution, as the learner is able to return to the expert with an hypothesis, or at least having done some basic checks suggested by the nature of the operation.

The key issue with this type of knowledge transfer is that, in the majority of cases, the expert is already overworked and has no time to spend standing over shoulders.

A secondary issue is that the expert may have to impart their knowledge, over time, to a number of different people, and this is inefficient.

The 'Virtual Expert'

From what has been discussed so far, it is clear that expert knowledge is required, but that tying up the expert in this process is seen as unproductive in most situations. We cannot get away from requiring time from the expert, but we can minimise this time and capitilise on it by recording the knowledge in the right way.

In part 2 of this article I will go into methods for capturing this knowledge in the most effective way.

Thanks for reading.
Allister.