 |
| Photo by PIXNIO |
“I write entirely to find out what I'm thinking” – Joan Didion (Note #1)
Sometimes I write these blogs to mentally process what I’ve learned and sometimes it’s self-therapy to sustain my energy over a long haul. This one is a little of both.
Over the last few years of this series, I’ve written about crucial IT project phases like building support, steering momentum, effective procurement, implementation, going live, and post go-live polishing.
This blog focuses on an overlooked phase of every IT project: internal documentation. “Internal” is the key word; this is not the vendor’s documentation on how the system works, it’s the quick reference your users need to do their jobs. It might not be about the technology at all… just your processes.
After definitions and bitching, there’s a brief pep talk. Then some lessons learned on tools you can use.
****************************************************************
All of the ideas expressed in this article are my personal statements and opinions, and do not reflect the opinions/statements of the City of Urbana.
****************************************************************
What Is “Internal” Documentation?
My IT Director answer: Organized information about your processes and systems that addresses frequently asked questions and lists instructions as numbered steps. Hopefully with pictures.
Over the first 20 years of my career, I wrote documentation such as: user manuals (Note #2), software error messages (Note #3), and release notes (Note #4). However, that was different from internal documentation because I worked for a software company, so user manuals were expected by customers. More importantly: software documentation only describes how the software is supposed to work. (Note #5)
Within an organization, documentation has a different purpose: it's not about how the software works, it's about how we work... using the software. (We used to call these “Procedures,” but I think that name is deprecated.) They're particularly important when you've adopted workarounds during implementation due to problems that couldn't be easily resolved… essentially: most implementations.
Internal documentation is incredibly helpful for two groups of people: people who are hired after the system’s go-live date and people who do infrequent but complex processes like yearly inventories.
Internal documentation is overlooked because it’s not necessary when you first go live. At that point the project team is still available and questions are answered by email, sometimes as a blast to all users. (Save those emails as pages for documentation!) Worth noting: most training materials are NOT good documentation. Training videos are an inefficient way to find an answer and hands-on materials (that give you specific entries to make in a practice environment) fall short in telling people how to deal with real-world scenarios.
The Bitching
By the time internal documentation is needed, everyone's moved on to other projects - so putting it together falls to whoever is left holding the bag of end-user support. That sucks, because they might not have been there during the implementation.
Good internal documentation is hard to write.
- It must be short, but instructive.
- You want detailed steps, but “step 73…” is scary.
- Creating it is time-consuming because you (should) step through the process while you describe it, that can require a lot of work for complex processes.
- Pictures take time to capture and annotate. (Pro tip: don't waste time adding arrows to your screen shots with a picture editor, just draw on them.)
So it's hard to write, but worse: like the cliché that 50% of advertising is wasted money, some documentation is wasted effort. People forget the documentation is there, it goes out of date, or the information is so often used that people don’t need it because they simply learn it.
The Pep Talk
To re-use a favorite metaphor, writing documentation is like flossing (your teeth… not the dance): no one likes to do it, many people don’t do it all, and it can take years before you realize the benefits. (Note #6)
Also like flossing, the benefits are real. Everyone saves time when we avoid entry mistakes. You help future users grow their understanding of the system by writing clear instructions AND explaining the “why” of the process to them at the same time.
I’m a realist about people: our most effective motivation is self-interest. So here are three selfish reasons to write internal documentation:
- To direct people to pre-written instructions so you don't have to answer the same questions repeatedly.
- To capture key decisions and settings made during implementation so that you don’t waste time digging through emails later to remember why.
- You might move on from the project (or leave the organization) and you don't want them continually asking you questions after you’ve left.
Assuming you’re in agreement that internal documentation can be good for your organization, what kind of tool should you use?
Documentation Tools – A Brief History
As described in Note #2, my 1990s introduction to documentation was a three-ring binder of printed pages. There is little to recommend the printed book model, except that you have something to read when the system is down.
Next came digital versions: a PDF document with the same text + a search. Searching is GOOD, but there was no change to content or format.
As the Internet took over, many people had the idea of putting documentation on web pages with pictures, hyperlinks, and even videos. Browser-based documentation is awesome! Single pages encourage you to work on small chunks of information and minimize time wasted on layout issues like pictures separated from their text.
In my current organization we went through three different iterations of browser-based tools, so here’s a history of that and why we moved from one model to another.
Simple Web Pages
When I started at the City in 2013, our internal documentation was hand-coded HTML with links to PDF documents and other pages. (Note #7) Much of it is generated by an ingenious script that shows the contents of Windows folders in a visual list. (See the picture below) It’s easy to expand, but formatting is finicky for the linked files – no_spaces_are_allowed_in_the_file_names – while HTML is easy to screw up.
Wikis
In 2016 we had to create documentation for a big rollout but had no budget for documentation. We found an end-user who was willing to help (thank you, Adam!) so we sought a tool that was easy to use, user friendly, and cheap.
As a solution, we selected Dokuwiki - an open-source Wiki. (I will not call Wikis “free.” As an open-source solution there’s no license cost; instead, it costs you time to install and manage.) Wikis have several benefits over HTML pages. For example, if you structure a page with headers then Dokuwiki creates a table of contents automatically. Another great feature: the media library stores files separately from the pages, so replacing an image updates all the pages that use it.
However, DokuWiki had two big drawbacks. First, editing a Wiki page is like coding HTML: logical, but not easy. Pro tip: use the preview button! Second, we found the Wiki install to be fragile. Adding plug-ins was a risky step (hosing our install more than once) and it was a maintenance hassle since we hosted it locally.
Heading into this most recent round of documentation during 2021, I thought “there has to be a better tool for this now!” And there was.
Knowledge Base Software
Generically known as “Knowledge Base Software” there are a number of systems out there with similar features, which are well described here: https://technicalwriterhq.com/knowledge-base-software/
We experimented with free trials on a few of them and found one that we liked for what seemed like a reasonable price. (The one we bought charges for each person who can edit, and we only have a few people creating content. I’m not going to say which one we bought, because it’s not important.)
The look and feel on these tools to create content is generally the same - a WYSIWYG editor. The WYSIWYG editor gives non-technical people a comfortable way to make updates, addressing the biggest Dokuwiki drawback. The picture below is one of these.
Some have options for themes, which is nice for formatting but can send you down a rabbit’s hole of visual possibilities. (My advice here is choose themes later and change them periodically to emphasize that content updates are ongoing.)
The best feature we found was to import text from Word or PDF files, which are 99% of existing documentation. My advice is don’t worry about formatting – just import (letting it clean the text as you go) and accept it might look wonky. If your documentation is visited so much that you are ashamed of how it’s formatted… that's a good problem. Then you can deal with the formatting.
Security is a consideration to mention. The two older methods described above kept the information on our premises and accessible only to people on our network. Moving it to the Internet entails some risk because documentation could have sensitive information in the text or (more likely) in a screen shot.
The software we chose let us allow connections from our organization's outbound IP address yet requires a sign-on from any other location. This nicely avoided the need to create user accounts for everyone, while hiding our documentation from the wild Internet.
Final Thoughts
During the time I’ve been writing and editing this blog (over six months!) I’ve nibbled away at the folder of emails labeled “need to document” – but it’s slow going. As I mentioned at the top, one reason for this piece was to convince myself that it was worth the effort.
We’re still in an awkward phase of migrating our documentation from one format to another. It’s a luxury to be able to do a gradual change, but no deadlines means it’s taking forever. Like other projects, momentum is important – it’s just harder in this case because documentation is always less urgent than most other tasks.
At the end of this process, I really am inspired. It took me six months to get here, but tonight as I finish this blog (and write this last paragraph) I finally see a path forward. Joan Didion is right: writing helped me figure it out. My path is to make the internal documentation platform fast, easy, and simple – so much that all the people writing those Word documents now will WANT to switch to a better tool. That’s my new mission.
Notes
Note #1 - Joan Didion died at the end of 2021 and a news story shared this quote, which stuck with me. Many of my blogs are an attempt to learn from the thoughts that flit through my head. Writing a blog entry gives me something to craft and polish, helping me to do the same with my ideas
Note #2 – Fresh out of college, I showed up for my first day at the worksite (our client’s office) and was treated with the traditional greeting: since no one had time for me, I was shown to a desk and given 3-ring binders with the system documentation to read. Truly, that was how I spent my first week. Two years later, on another project, I spent twelve months revising every page of that same manual to describe the many software changes we’d customized for that client. That was a valuable experience – it taught me every nook and cranny of the software - but it was an excruciating task to work on for a full year.
Note #3 - Later in my career I wrote and reviewed software designs, including error messages. This was a good idea for the designer to write them: don’t leave error message writing to the programmers! Error messages deserve more effort than they get, because they need to stand on their own as self-documentation. We've all been frustrated by error messages that are circular and useless, like this Windows classic that’s both: ERROR_INVALID_DATA (0xD) “The data is invalid.” A good error describes the condition that caused the error, explains the problem, and suggests a resolution. It’s more work to do this but for software as widely used as Windows, just imagine how many person-years of effort could be saved with a little more effort from designers and programmers!
Note #4 – As a Product Manager, I was also responsible for release notes. In general, these are vastly under-used because not enough people pay attention to upgrade releases and try to understand what new features exist that can benefit them! It’s a topic I touched on in part 3 of the Tectonic series about the phase of the implementation that continues after you go live. Not every feature is needed at your organization but combing through release notes is like prospecting: there are gold nuggets out there. Furthering that metaphor – the nugget has to be processed to gain its full value, which means software testing, teaching people the changes, and updating internal documentation. It's work, but it pays off.
Note #5: “Supposed to” because it deserves this modifier: “as understood by the people who wrote the documentation.” Let’s cut them some slack, please. All they had were the designs, as updated during programming. Maybe this should be another frame in the tire swing project management cartoon.
Note #6 – I also used this metaphor in Tectonic Speed Part 3. Flossing resonates as a metaphor for me because I had periodontal issues early in my 30s that required surgery – so I “got religion” on flossing after that. If you really want to get me riled up, ask me about my favorite dental floss that was mysteriously dropped in 2019… angering me and many other loyal fans! https://twitter.com/jnjnews/status/1281753769513017344?lang=en
Note #7 - OK… most of it is still that. But it's hard enough to create new documentation. Redoing old documentation is a massive effort for only an incremental improvement.