<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Robert Freiberger on Medium]]></title>
        <description><![CDATA[Stories by Robert Freiberger on Medium]]></description>
        <link>https://medium.com/@rfreiberger?source=rss-75bb9941242------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*BvkDuKZEyMUjgzdHlItU6w.png</url>
            <title>Stories by Robert Freiberger on Medium</title>
            <link>https://medium.com/@rfreiberger?source=rss-75bb9941242------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 07:00:03 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@rfreiberger/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The Balance of Documentation]]></title>
            <link>https://medium.com/@rfreiberger/the-balance-of-documentation-8ea25441c9d9?source=rss-75bb9941242------2</link>
            <guid isPermaLink="false">https://medium.com/p/8ea25441c9d9</guid>
            <category><![CDATA[linux]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[operations]]></category>
            <dc:creator><![CDATA[Robert Freiberger]]></dc:creator>
            <pubDate>Mon, 12 Jun 2017 08:42:41 GMT</pubDate>
            <atom:updated>2017-06-12T08:45:09.271Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*1Vg_kVZLH1j5OPDxrTeKfg.jpeg" /><figcaption><a href="https://www.flickr.com/photos/mujitra/">https://www.flickr.com/photos/mujitra/</a> <a href="https://flic.kr/p/9z2R2m">https://flic.kr/p/9z2R2m</a></figcaption></figure><p>Years ago one of my favorite hobbies was building remote control cars. The type where you purchase a kit and have to assemble the entire car from prepackaged parts following the instructions. Since I bought a few different cars I found that certain companies included excellent instructions which mentioned some tips on the build process while others lacked these details. After my first car, I became decently able to assemble the next car even if it was from another brand since I basically knew where each part would go based upon experience. As time went on, I could solve most car related issues by simply running the car through a few trouble shooting steps.</p><p>If the car’s steering was slow, it’s a possible weak servo or steering linkage was worn out. If the car was had power issues, it might be a broken link in the battery pack or even a worn motor. If the car would land too rough after a jump, then it would need thicker shock oil or different springs. The list of solutions to problems is near endless but I was able to fix most of the common problems I found racing with my friends. Combined with the solutions I found we shared these with our group and soon the entire circle of friends would implement these same solutions.</p><p>As with building a remote control car, or starting a new job, having solid documentation is critical to the daily work. In the recent months, I moved from one team to another, which is less reactive work and more proactive. My previous experience does not heavily overlap with my new role leading me to rely upon the documentation. As I read over each team document, I found that some were vague leaving little to complete without some critical pieces of information. Often you find this in any workplace, a list of steps to complete but some steps are shared through local tribal knowledge. A common example is steps to complete an administration task but the location of the script or tool is not mentioned, it’s assumed the reader knows of the shared tool host.</p><p>Part of my responsibilities is updating and writing documents to stay updated as our platform changes so these gaps are very important to cover. In my normal writing mode, I read the rough steps, then follow them precisely, if I need to find a gap, it’s noted and which is added to the final document. But as I started to write a document how to use our monitoring system, I found some issues with this process. It was taking an extremely long time to write a guide that could take minutes to complete.</p><p>Here’s an example. I write a document how to create new alerts in a monitoring system. So I need to assume that the reader has never used this monitoring system before, so now I need to include an introduction to the use of the monitoring system. Which includes how to use the monitoring dashboard, then which applications to monitor. As you can see it’s a near endless rabbit hole unless I just focus solely on the monitoring platform.</p><p>Another problem which is becoming more and more common is duplicate efforts to create common documents. Similar to software development, sharing a common library of code to complete core tasks is more efficient than having the same code written from scratch each time. While I’m trying to be complete in my documentation, I’m sure some of my topics have been covered in another document, possibly even in more detail.</p><p>What I found in my time spent writing is that you first need to define an audience for your document. Let’s go back to the monitoring platform example. Here are a few things to list of basic knowledge.</p><p>1) The reader understands core monitoring, how it works and why<br>2) The reader understands how to use git, as our configs are entered into production by Jenkins<br>3) The reader has read our internal core documents about monitoring and building a custom dashboard</p><p>Right away, we just eliminated a vast majority of our writing time by asking the reader if he or she is at the required technical level of the document. This is actually a problem I’ve seen in many “intro to programming” books. Trying to include everything you need to get started in programming can be a nearly endless list of technical topics and ideas. So you start to break down these topics into short summaries which leave the reader with more questions than answers.</p><p>Once you know that the reader is at the level of having the core basic knowledge required for the document, then you can write a more focused guide covering only what is unique to your team instead of covering or overlapping previous documents on the generic topic. While it’s more difficult to make that decision, I personally find it’s much easier to manage and write, plus the biggest task, keeping the document updated with changes.</p><p>A few years ago I was tasked with creating an intro guide to using Chef, the configuration management tool for our team. To be honest, this was a guide that basically merged the official Chef documentation and specialized it for our internal changes (how we used Jenkins and Ruby testing). Overall it came out great, many people still reference my guide while writing their own but I quickly found the problems with trying to cover all of the topics in a single document. It’s impossible.</p><p>Moving forward, while I enjoy writing detailed documents, I have to pull myself away from writing too much for the simple fact that it’s not very efficient. I should not be spending hours or even days on the document which will only save a person minutes on a task. As with programming, you may get stuck on an issue, and there is usually a module or package already written for your task. Take this approach and work on the real problem, what is not documented, not trying to rewrite the entire guide. You only need to write for what is missing, not what is already written.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8ea25441c9d9" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>