Documenting Knowledge [closed]

Question

I find a lot of people, as well as companies don't document their knowledge, or, do a poor job of it. I'd like to discuss what has been found to work well and not so well when it comes to doing this in the hope that we'll be able to assist one another.

Wiki

I use Dokuwiki hosted on my webserver. My job requires me to be across a large range of topics, so having my notes easily accessible and available regardless of which PC I am using is extremely useful.

I have lost count of the number of times where I have documented something a few years ago which has come in handy later on down the track. The best thing is that as it is my own notes, I can write about certain "gotchas" which I encountered which I may forget some time in the future. On the other hand, Googling and bookmarks won't afford me this. Further to this, if I were to use bookmarks alone I run the risk of those websites not being around when I may need them in the years to come. There are the "archiving" websites, but I'd prefer not to have to rely on them if I didn't have to.

Having said the above, I'm definitely not against bookmarking. I have found a wiki entry with my own notes as well as useful external links to websites contained inside the wiki entry to be a killer combination. This way the information is all in one spot. If I'm worried about a useful website not being around when I need it, I use a HTML to PDF converter and attach it to the wiki too.

File Syncing

I have found File Syncing to be a huge benefit as well. There are multiple options out there, most of which are free. As I don't trust the cloud with my data, I use BoxCryptor to encrypt my filenames and files.

Using the above two solutions I have all of my notes and all of my files with me everywhere I go, regardless of which PC(s) I use.

Answer 1

We use the following tools for different types of documentation:

• RackTables - Holds physical rack layouts, cabling, asset tracking, IPAM (IP address management), and change logs.
• Rancid - Automatically backs up all configuration changes in to SVN from all of our switches, routers and firewalls. This provides automatic documentation and tracking on changes.
• MediaWiki - All code snippets, procedures, and detailed customer information is logged in wiki form as it's easy to edit for all while providing good version history.
• GitHub - All large configuration sets (eg for Nagios or Bacula) are stored in private repositories in GitHub. We moved to Git from SVN around a year ago as it provides far superior tracking and delegated maintainership.

Answer 2

Rather than focus on a couple tools that you use I would focus on what type of data is worth documenting.

I find that the most overlooked document is the "why" document that should be a companion to a standards document. This "why" document would describe the design options that were reviewed and the reasoning behind the choice that was made. Months or years later you can then look back and see if the reasoning is still sound and make changes as necessary. It also can prevent rehashing of old arguments by summarizing the arguments against the alternate designs.

Answer 3

Tools

We are currently using a private SVN server for knowledge documentation. Our team is small and savvy (and includes people mostly familiar with SVN including someone who commits code to the Apache Subversion project). We also track knowledge in other areas as well. Keep in mind our operation is small (just a few individuals) and so the emphasis is on coordination and making sure we don't forget stuff we shouldn't.

We are in the process (which may take some time) of fully integrating the CMS/FAQ/etc, tracking with our ERP (which is where we store detailed customer info) but this may take quite some time. One of our goals is a very highly integrated system where changes made in the ERP get rolled out automatically to the network (both at the network and host level), and where knowledge and information is tightly bound to that.

Use

Regarding network engineering there are two critical aspects for us, namely periodic review (documenting is great, but it is useless if you don't periodically do something with it). This is particularly important when it comes to security knowledge. What is our current threat profile we are worried about? What are we doing about this? Are either of these things can can be improved on?

In general, documented knowledge should be both reviewable and periodically reviewed.

Answer 4

I think that the documentation is fundamental and all the answers (especially Mike's one IMHO) pointed out very good reasons to do so.

What I would like to add is that, I think the choice of the tool should be done on the base of the "audience". That is: if one needs to document a developed simulator for him and some colleagues, perhaps GitHub is sufficient. But, consider the case in which the same simulator should be used in an academic course: then, probably, it is worth to provide to students also a rough illustration guide to explain the basic functionalities.

Answer 5

I think this is a great discussion, and although I read @Jody's comment, I haven't seen an answer proposing Google Docs as a collaborative documentation solution. Although I've seen reports of unavailability of that particular Google service from time to time, I know many large institutions use it because of its familiarity to its employees and its convenience. For example, Harvard University uses Google Docs for many of its internal documentation that requires collaboration.