6

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.

3
  • 2
    While I like the topic, I don't think open-ended discussion fits into the Q&A format of Stack Exchange. Topics like this are better suited for a discussion forum. May 8 '13 at 1:53
  • Fair enough Stretch :) I'm still very new to StackExchange so apologies if my post is not well suited.
    – OzNetNerd
    May 8 '13 at 5:37
  • Although based on votes, this question is pretty popular, it is likely to be closed. meta.networkengineering.stackexchange.com/questions/87/… May 19 '13 at 11:05
9

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.
6
  • We use Confluence (atlassian.com/software/confluence/overview/…) for a lot of out internal documentation (technical and other). It has an excellent Gliffy plugin (gliffy.com) which means we don't need Visio which is great as we're mostly on Linux and OS X. May 8 '13 at 7:05
  • Confluence does look very nice, but it strikes me as something that's quite specialist to get up and running. Not that that's a reason to not do it, but am I right in saying that? I have been looking for something simpler than MediaWiki for the less markdown inclined of our users. May 8 '13 at 7:07
  • When you say specialist to get up and running do you mean the install process or the admin and use of the Confluence system itself once setup? Confluence is simple to use, all our guys, technical and non-technical find it easy to use. May 8 '13 at 8:28
  • I'm referring to getting it working the way you want, templates etc. I may be entirely wrong, this is third hand experience. Hence asking for opinions :) May 8 '13 at 9:20
  • 1
    We've found it quite easy, it's probably been more difficult putting the people processes round it. As it can do a lot then it's easy for people to go off on a tangent and do their own thing. There's some really useful plugins like page approval, inline talk, Evernote import, Google Docs sync etc. Plus if you need bug tracking then it integrates really well with JIRA (as you'd expect with them both being from Atlassian). May 8 '13 at 12:34
8

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.

1
  • You've got a very good point, though it appears that I wasn't clear with the type of knowledge I was referring to. What I meant was that, for example, if I were to do a QoS config which may come in handy years down the track, I'll put it in the wiki rather than configure the router and forget which router it was. Another example would be during my studies for the WAASSE certification. Rather than put all my notes in a Word document and file it away somewhere, I put all of it in to the wiki.
    – OzNetNerd
    May 8 '13 at 2:48
2

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.

2

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.

1
0

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.