<?xml version="1.0" encoding="UTF-8" ?><!-- generator=Zoho Sites --><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><atom:link href="https://www.bolbeck.com/blogs/tag/documentation/feed" rel="self" type="application/rss+xml"/><title>Bolbeck LLC - Blog #Documentation</title><description>Bolbeck LLC - Blog #Documentation</description><link>https://www.bolbeck.com/blogs/tag/documentation</link><lastBuildDate>Wed, 10 Dec 2025 22:45:03 -0800</lastBuildDate><generator>http://zoho.com/sites/</generator><item><title><![CDATA[A better approach to project documentation]]></title><link>https://www.bolbeck.com/blogs/post/A-better-approach-to-project-documentation</link><description><![CDATA[Using word processors to create and manage project documentation can cause a number of significant issues in the long run. Most of these issues can be solved by using Markdown and plain text documents.]]></description><content:encoded><![CDATA[<div class="zpcontent-container blogpost-container "><div data-element-id="elm_gFCSRvFlSWSlRknSOvEe8Q" data-element-type="section" class="zpsection "><style type="text/css"></style><div class="zpcontainer-fluid zpcontainer"><div data-element-id="elm_FJL2FyBkQxCMSURipUMTeg" data-element-type="row" class="zprow zprow-container zpalign-items- zpjustify-content- " data-equal-column=""><style type="text/css"></style><div data-element-id="elm_1XQETGhDQjK0TA5nbxdgcQ" data-element-type="column" class="zpelem-col zpcol-12 zpcol-md-12 zpcol-sm-12 zpalign-self- "><style type="text/css"> [data-element-id="elm_1XQETGhDQjK0TA5nbxdgcQ"].zpelem-col{ border-radius:1px; } </style><div data-element-id="elm_GFH1soqpTCmiwkZAxl2mUw" data-element-type="heading" class="zpelement zpelem-heading "><style> [data-element-id="elm_GFH1soqpTCmiwkZAxl2mUw"].zpelem-heading { border-radius:1px; } </style><h2
 class="zpheading zpheading-align-center " data-editor="true">Word processors spell trouble for your project documentation&nbsp;</h2></div>
<div data-element-id="elm_q6_t1M3pkdfVHQU3YWin-Q" data-element-type="imagetext" class="zpelement zpelem-imagetext "><style> [data-element-id="elm_q6_t1M3pkdfVHQU3YWin-Q"].zpelem-imagetext .zpimage-text, [data-element-id="elm_q6_t1M3pkdfVHQU3YWin-Q"].zpelem-imagetext .zpimage-text :is(h1,h2,h3,h4,h5,h6){ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_q6_t1M3pkdfVHQU3YWin-Q"].zpelem-imagetext{ border-radius:1px; } </style><div data-size-tablet="" data-size-mobile="" data-align="left" data-tablet-image-separate="" data-mobile-image-separate="" class="zpimagetext-container zpimage-with-text-container zpimage-align-left zpimage-size-small zpimage-tablet-fallback-small zpimage-mobile-fallback-small hb-lightbox " data-lightbox-options="
            type:fullscreen,
            theme:dark"><figure role="none" class="zpimage-data-ref"><span class="zpimage-anchor" role="link" tabindex="0" aria-label="Open Lightbox" style="cursor:pointer;"><picture><img class="zpimage zpimage-style-roundcorner zpimage-space-none " src="/images/scrap-2049626_640.jpg" size="small" alt="Documentation pile" data-lightbox="true" style="height:101px;width:152px;"/></picture></span></figure><div class="zpimage-text zpimage-text-align-left " data-editor="true"><p><span style="color:inherit;"></span></p><p><span>Modern day word processors are as ubiquitous as sliced bread. People use them for everything from&nbsp;writing &nbsp;a receipt to a business plan. However these editors are also probably the worst choice when writing documentation. Before you call me crazy or seek to send me a politely worded note online, think about the last project you used a word processor like Microsoft Word to write the&nbsp; documentation. Do any of the scenarios below sound familiar?</span></p></div>
</div></div><div data-element-id="elm_E2K6xHk9awaQAB2f32zEvw" data-element-type="imageheadingtext" class="zpelement zpelem-imageheadingtext "><style> [data-element-id="elm_E2K6xHk9awaQAB2f32zEvw"].zpelem-imageheadingtext .zpimage-text, [data-element-id="elm_E2K6xHk9awaQAB2f32zEvw"].zpelem-imageheadingtext .zpimage-text :is(h1,h2,h3,h4,h5,h6){ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_E2K6xHk9awaQAB2f32zEvw"].zpelem-imageheadingtext h3.zpimage-heading{ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_E2K6xHk9awaQAB2f32zEvw"].zpelem-imageheadingtext{ border-radius:1px; } </style><div data-size-tablet="" data-size-mobile="" data-align="right" data-tablet-image-separate="" data-mobile-image-separate="" class="zpimageheadingtext-container zpimage-with-text-container zpimage-align-right zpimage-size-small zpimage-tablet-fallback-small zpimage-mobile-fallback-small hb-lightbox " data-lightbox-options="
            type:fullscreen,
            theme:dark"><figure role="none" class="zpimage-data-ref"><span class="zpimage-anchor" role="link" tabindex="0" aria-label="Open Lightbox" style="cursor:pointer;"><picture><img class="zpimage zpimage-style-roundcorner zpimage-space-none " src="/images/adult-1850268_640.jpg" data-src="/images/adult-1850268_640.jpg" size="small" data-lightbox="true" style="height:151.5px;width:101px;"/></picture></span></figure><div class="zpimage-headingtext-container"><h3 class="zpimage-heading zpimage-text-align-left " data-editor="true">Typical documentation issues</h3><div class="zpimage-text zpimage-text-align-left " data-editor="true"><p><span style="color:inherit;"></span></p><ul><li style="margin-bottom:3px;"><span style="font-weight:bold;">Keeping documentation up to date</span>: The team finishes the application and proudly delivers the related documentation. All is great in the world. Three releases later, a user opens the documentation and not even the screenshots match the application. This scenario is so frequent, the running &nbsp;joke is that the documentation is obsolete the moment it is written.&nbsp;</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">Determining which version of the documentation to use</span>: The team updates and publishes all documents. However, someone notices that the new version does not include the latest changes and may in fact have reverted to an older version in some areas. The team realizes some members used v3 of the documents for their updates while others used the newer v4.</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">Keeping track of the documentation master copy</span>: Documents that have more than one author sooner or later end up with multiple&nbsp;master&nbsp;copies. As people email documents, it is easy to loose track about who has the master. It is all fun and games until someone ends up drinking a few gallons of coffee at two AM, merging multiple documents and hoping that nobody notices how he skipped a whole section.</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">The documentation graveyard</span>:&nbsp; It is unfortunately very common to be tasked to update an application just to find out all the documentation exists in an unmarked grave somewhere in a documentation graveyard on a corporate hard drive somewhere.&nbsp; When the documentation is eventually found (if it is found at all), trying to go through it feels like being Indiana Jones in the Temple of Doom.&nbsp; There are mummified code blocks chasing you, poisonous screenshot darts and overall evil forgotten library references that really make the hairs in the back of your hair stand. On the plus side, you get to feel like&nbsp;Indiana Jones, so I guess it is not all bad.</li><li><span style="font-weight:bold;">Formatting hell</span>: This is a typical scenario when trying to edit someone else's document. Surprisingly, the moment you add a simple bullet point, the formatting on the whole page just breaks. Little did you know the original author was a triple document processor black belt with a masters in nested tables. You hunker down, put on your helmet and hope for the best as you wade into the abyss of formatting hell.&nbsp;</li></ul></div>
</div></div></div><div data-element-id="elm_ZpI7Z5W5FM1dH52Nk_vbHw" data-element-type="imageheadingtext" class="zpelement zpelem-imageheadingtext "><style> [data-element-id="elm_ZpI7Z5W5FM1dH52Nk_vbHw"].zpelem-imageheadingtext .zpimage-text, [data-element-id="elm_ZpI7Z5W5FM1dH52Nk_vbHw"].zpelem-imageheadingtext .zpimage-text :is(h1,h2,h3,h4,h5,h6){ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_ZpI7Z5W5FM1dH52Nk_vbHw"].zpelem-imageheadingtext h3.zpimage-heading{ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_ZpI7Z5W5FM1dH52Nk_vbHw"].zpelem-imageheadingtext{ border-radius:1px; } </style><div data-size-tablet="" data-size-mobile="" data-align="right" data-tablet-image-separate="" data-mobile-image-separate="" class="zpimageheadingtext-container zpimage-with-text-container zpimage-align-right zpimage-size-small zpimage-tablet-fallback-small zpimage-mobile-fallback-small hb-lightbox " data-lightbox-options="
            type:fullscreen,
            theme:dark"><figure role="none" class="zpimage-data-ref"><span class="zpimage-anchor" role="link" tabindex="0" aria-label="Open Lightbox" style="cursor:pointer;"><picture><img class="zpimage zpimage-style-roundcorner zpimage-space-none " src="/images/manicure-1786315_640.jpg" data-src="/images/manicure-1786315_640.jpg" size="small" data-lightbox="true" style="height:101px;width:152.33px;"/></picture></span></figure><div class="zpimage-headingtext-container"><h3 class="zpimage-heading zpimage-text-align-left " data-editor="true">How word processors enable bad behaviors</h3><div class="zpimage-text zpimage-text-align-left " data-editor="true"><p style="margin-bottom:10px;">You are probably thinking: what does that have to do with word processors, these are all just bad processes. And you would be partially right, these are consequences of bad processes but the root cause is using the wrong tool for the job.&nbsp; While word processors are great for many tasks, they are not good for projects because:</p><p></p><p></p><ul><li style="margin-bottom:3px;"><span style="font-weight:bold;">They are meant to be used to write single documents</span>: You write a document save it and move on to the next one. There is no real concept of these documents being part of a project.</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">They help us write shareable documents</span>. These documents are expected to be easy to share and email. Unfortunately, this means that very quickly there is no single source of truth.</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">They provide no real way to track changes</span>. Yes, it is true that word processors have document change tracking. But, it is way too easy to accept all changes, disable the tracking or even copy the document . At that point all history is lost.</li><li style="margin-bottom:3px;"><span style="font-weight:bold;">They allow us to&nbsp; store files anywhere</span>.&nbsp;Users can store documents anywhere they want, and I mean anywhere: Laptop, server, usb drive, google drive. Finding the right files becomes...well...a bit of a challenge, if you find them at all.</li><li><span style="font-weight:bold;">They provide endless set of features</span>.&nbsp;These features are meant to make documents look great. However, does documentation need to look like a tribute to Michelangelo and his Sistine chapel? Not really. While they should look professional, they do not need to have&nbsp; flashy formatting. More importantly, the team maintaining the documents nowadays&nbsp; is the same team doing development on the project and does not have the time for endless formatting matches. They need a simple tool to write documentation as fast and accurately as possible.</li></ul></div>
</div></div></div><div data-element-id="elm_UCYT0sX1GWkbYfmsEFJt7g" data-element-type="imageheadingtext" class="zpelement zpelem-imageheadingtext "><style> [data-element-id="elm_UCYT0sX1GWkbYfmsEFJt7g"].zpelem-imageheadingtext .zpimage-text, [data-element-id="elm_UCYT0sX1GWkbYfmsEFJt7g"].zpelem-imageheadingtext .zpimage-text :is(h1,h2,h3,h4,h5,h6){ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_UCYT0sX1GWkbYfmsEFJt7g"].zpelem-imageheadingtext h3.zpimage-heading{ font-family:Noto Sans,sans-serif; font-weight:400; } [data-element-id="elm_UCYT0sX1GWkbYfmsEFJt7g"].zpelem-imageheadingtext{ border-radius:1px; } </style><div data-size-tablet="" data-size-mobile="" data-align="left" data-tablet-image-separate="" data-mobile-image-separate="" class="zpimageheadingtext-container zpimage-with-text-container zpimage-align-left zpimage-size-small zpimage-tablet-fallback-small zpimage-mobile-fallback-small hb-lightbox " data-lightbox-options="
            type:fullscreen,
            theme:dark"><figure role="none" class="zpimage-data-ref"><span class="zpimage-anchor" role="link" tabindex="0" aria-label="Open Lightbox" style="cursor:pointer;"><picture><img class="zpimage zpimage-style-roundcorner zpimage-space-none " src="/images/office-381228_640.jpg" data-src="/images/office-381228_640.jpg" size="small" data-lightbox="true" style="height:136px;width:181.38px;"/></picture></span></figure><div class="zpimage-headingtext-container"><h3 class="zpimage-heading zpimage-text-align-left " data-editor="true">A Better way to handle documentation</h3><div class="zpimage-text zpimage-text-align-left " data-editor="true"><p style="margin-bottom:10px;"><span style="font-size:12px;">&nbsp;</span>Interestingly, these problems are the same problems that the software community&nbsp; solved to track the code for applications. Nowadays, code is located in a centralized location, all changes are tracked,&nbsp; there is one source of the truth, code editors have been optimized to maximize the developer's time and tools have been created to simplify the formatting.&nbsp; Can we apply those learnings to the documentation process?</p><p></p><p>This is where a new breed of text editors fits. They use a simplified text based toolset called Markdown to treat documents as if they were code files. The concept is simple: The author uses&nbsp;simple text to write content, character combinations to denote formatting cues and then have the editor automatically transform them into the correct visual formatting on demand. For example:, an author could simply type the '-' character to indicate an unordered list item (bullet point) . This and other examples can be seen in the table below and the <a href="https://www.markdownguide.org/basic-syntax">markdown guide</a> is a good reference for the full markdown syntax</p></div>
</div></div></div><div data-element-id="elm_7kSsZzC1--8BEtQ80wac8w" data-element-type="table" class="zpelement zpelem-table "><style type="text/css"> [data-element-id="elm_7kSsZzC1--8BEtQ80wac8w"].zpelem-table{ border-radius:1px; } [data-element-id="elm_7kSsZzC1--8BEtQ80wac8w"] .zptable{ width:100% !important; } </style><div class="zptable zptable-align-center zptable-header-light zptable-header-top zptable-cell-outline-on zptable-outline-on zptable-style- " data-width="100" data-editor="true"><br><table style="text-align:center;height:220px;"><tbody><tr style="height:15.5px;"><th style="text-align:center;width:33.3333%;"> <span style="font-size:12px;">Desired Formatting</span></th><th style="text-align:center;width:33.3333%;"><span style="font-size:12px;"> Markdown</span></th><th style="text-align:center;width:33.3333%;"><span style="font-size:12px;"> Generated formatted Text</span></th></tr><tr style="height:5.5px;"><td style="text-align:left;width:33.3333%;"> Bullet point</td><td style="text-align:left;width:33.3333%;"> - list item</td><td style="width:33.3333%;"><ul><li style="text-align:left;">list Item<br></li></ul></td></tr><tr style="height:21.5px;"><td style="text-align:left;width:33.3333%;"> Bold text</td><td style="text-align:left;width:33.3333%;"> **bold**</td><td style="text-align:left;width:33.3333%;"> bold</td></tr><tr style="height:40.5px;"><td style="text-align:left;width:33.3333%;"> Link</td><td style="text-align:left;width:33.3333%;"> [Bolbeck](Bolbeck.com)</td><td style="text-align:left;width:33.3333%;"> <a href="/" title="Bolbeck" rel="nofollow">Bolbeck</a><a href="/#Bolbeck" rel="nofollow"></a><a href="/" target="_blank"></a></td></tr><tr style="height:17.5px;"><td style="text-align:left;width:33.3333%;"> Heading 2&nbsp;</td><td style="text-align:left;width:33.3333%;"> ## Heading 2</td><td style="text-align:left;width:33.3333%;" class="zp-selected-cell"> <span style="font-size:18px;">Heading 2</span></td></tr></tbody></table></div>
</div><div data-element-id="elm_bb-SYlxf8Ma94Hag_Zzeow" data-element-type="text" class="zpelement zpelem-text "><style> [data-element-id="elm_bb-SYlxf8Ma94Hag_Zzeow"].zpelem-text { font-family:Noto Sans,sans-serif; font-weight:400; border-radius:1px; } [data-element-id="elm_bb-SYlxf8Ma94Hag_Zzeow"].zpelem-text :is(h1,h2,h3,h4,h5,h6){ font-family:Noto Sans,sans-serif; font-weight:400; } </style><div class="zptext zptext-align-left " data-editor="true"><p style="margin-bottom:3px;">The benefits of Markdown come from the fact that everything is plain text in the file, without all the extra hidden information that word processors put in the file. This means that:</p><ul><li style="margin-bottom:3px;"><span><span style="font-weight:bold;">Documents&nbsp;can be tracked</span> in the same change tracking system as the application code</span></li><li style="margin-bottom:3px;"><span><span style="font-weight:bold;">User can focus on writing</span> and let the system deal with the visual formatting</span></li><li style="margin-bottom:3px;"><span><span style="font-weight:bold;">Single official source of the documentation</span> is stored in the centralized management system</span></li><li style="margin-bottom:3px;"><span style="font-weight:bold;">All&nbsp;changes are tracked in history</span> all the way down to the individual change</li><li style="margin-bottom:3px;"><span><span style="font-weight:bold;">Most markdown editors enablefast, accurate writing</span>.&nbsp; Additionally, most modern code editors support markdown allowing seamless switching between code and documentation.</span></li><li style="margin-bottom:3px;"><span style="font-weight:bold;">Documentation is&nbsp;versioned alongside the code</span> making it simple to determine if the documentation has been updated with the latest code changes. It also simplifies the creation of release notes as every time a change is made to a document, a comment must be made in the central repository about the nature of the change.</li><li style="margin-bottom:10px;"><span><span style="font-weight:bold;">Easy conversion of markdown content into all major formats</span> like .doc or .pdf&nbsp; for external distribution is supported by most markdown editors.</span></li></ul><p style="margin-bottom:3px;"><span>While markdown is not the only text mark up solution ( <a href="http://asciidoc.org">AsciiDoc</a> is another one for example),&nbsp; it is the de facto industry standard. In fact, there are a number of popular Markdown editors like:</span></p><ul><li style="margin-bottom:3px;"><span><a href="https://bywordapp.com">Byword</a></span></li><li style="margin-bottom:3px;"><span><a href="https://ia.net/writer">iA Writer</a></span></li><li style="margin-bottom:10px;"><span><a href="https://www.mkdocs.org">MKDocs</a> (full documentation site generator)</span></li></ul><p></p><p>It is also supported by popular code editors like <a href="https://code.visualstudio.com">Visual Studio code</a> , <a href="https://atom.io">Atom</a> and <a href="https://www.jetbrains.com/pycharm/?fromMenu">Pycharm</a></p></div>
</div></div></div></div></div></div> ]]></content:encoded><pubDate>Mon, 26 Aug 2019 20:18:12 -0500</pubDate></item></channel></rss>