Episode 21 - You did know there is a script for that?

Devops Mastery

Bob from Minneapolis sent us some great feedback and a couple of great questions. In this post we are going to tackle communicating what scripts are available and what they do. I spend a lot of my time as a consultant writing up documentation. At most sites I am pretty sure the work is lost before I get out the door on my last day. So how did I try to handle this before as a Tech Lead? To be completely honest it always seems to be hit or miss. I have never found a single solution that works for all purposes and with all types of people. Let's face it we as WetWare are the most difficult to communicate with. Hardware wants power and bits to process. Software wants data and other inputs. But humans, a.k.a WetWare, all want something different. There are all kinds of factors from Gender to skill level to happiness with their current job that can affect and require different types of communications. Since we can't solve all of these problems, and at least one is unsolvable, we need to focus on what we can. Let's start with the one thing I know doesn't work and that is network file shares. It's been my experience that network file shares full of Word or Text documents are where good documentation goes to die. There is no automatic version tracking, you can never find a structure everyone will agree on, and unless you ingest it into a database somehow it's basically unsearchable. Since no one can ever find the document they are looking for or be sure it's the most current it quickly becomes a thing we do because Management says we have to not because we find it at all useful. Wiki's can work well and solve at least a few of these issues but they still aren't a cure all. They tend to be search-able and track versions. They still have the structure issue though. If Google has taught us nothing it is that we don't have to care how things are stored in the great database that is the Internet as long as it can be searched we can find anything. With that being said the structure is probably less of an issue with a Wiki because they are generally speaking searchable. So it's always going to stay on my list. There are so many options from your own version of the Wikipedia to all javascript single page solutions. It's still not perfect but it works better than a file share and generally looks better too. Version Control systems like Git believe it or not when combined with something like gitlabs, gitblit, or github(public or private) can also work as a suitable solution. It keeps the documentation with the code and is search-able. Since the code and documentation are kept together it works a lot better for scripts and programs than it does for something like the procedure to shutdown your whole data center. It doesn't mean it can't or shouldn't use it just that it may not work great for all use cases. So again we are close but still not a home run. Knowledge-base/Content Management Systems/anything like it all work to varying degrees. This concept is really more implementation and software dependent. For the most part the difference between these and a Wiki is generally the flexibility to document changes to the documents and who made them. These systems tend to be very rigid and generally require defining a taxonomy to make them work efficiently. There is nothing wrong with defining a taxonomy but it normally provides very little reward for the time and frustration put into them to get everyone on the same page. They generally just become difficult to manage over time and then grow less useful as people stop putting the effort in. What seems to work in a lot of environments is a blending of the Wiki and Version Control(GIT) concepts. Yes your documentation ends up somewhat scattered but if everyone knows where to look for which kind of document then it works pretty well. I generally suggest putting things like procedure and policy items go in a Wiki so they are accessible to everyone. Then for things that are focused on an applications whether purchased or internally developed being kept in a Version Control system with the code or binaries. This keeps the specifics of applications which tend to change more often with the related applications. The wiki can then be used for the things that should be more accessible and slower changing like the procedures for deploying that application. At the end of the day the best system is the one that wins the popularity contest in your organization or team. If the whole team hates wiki's then don't use them. At the same time if it's just the one user who doesn't want to use a wiki then maybe it's time to talk to them about leaving your Company. So go now and document something and put it where you think everyone should find it. Then ask everyone to send you an e-mail with the first place they looked. If the majority were looking in the right place then you found your location.