Summary
How do you transfer knowledge about a system in an optimal way, without forever being the 'guy who knows'? What practices will help you exit gracefully? Or, even if you aren't leaving this area of the project, how do you lessen the documentation burden?
Advertisement
On the What questions would you ask? thread, Marc Loxton says:
I want to do this in an agile way though not by writing a truckload of documentation describing the tech aspects of the system, the direction i want to go with it, which parts I want to phase out and what they should be replaced with etc. I've been having some success with pair programming for some tasks but I'm wondering what do others do to share the knowledge without becoming a novelist? A Wiki with a list of key points? A Brief README file and verbose comments in key areas of the code/tests?
I think the answer is all of the above
You also want to leave a legacy which can be maintained
README documents (I start with AAREADME so it stands out) are essential when looking at a directory and trying to figure out things like:
What tools do I need to be able to use this code?
Where are the tests?
What is this stuff for, what projects does it relate to? (great spot for Wiki links).
What build settings where changed for this Visual Studio project other than just running the AppWizard?
What environment variables need setting to be able to build, run, debug?
Wikis are good, I'm a big believer. They work well with other link-friendly systems. Your issue-tracking system and repository should make it easy to copy stable links to embed in wiki pages.
Verbose comments in key areas are really good if they will be maintained. I am a huge fan of Doxygen because it makes it very easy to embed comments right next to code as well as writing independent pages describing the software. Unlike many other code documentation systems, Doxygen can parse your C++, Java, Python or other code and immediately generate class diagrams, lists of classes and members, call graphs etc. You can choose to generate fully annotated, hyperlinked documentation so it is easy to go from explanation to code and back.
I agree with almost everything you say here. My personal emphasis would be on leaving a "project-server" up and running. This server would: * automatically build the software, run a comprehensive set of tests and publish results in a browsable form; and I'd try and leave all these tests passing! * generate up to date documentation, again in a browsable form (I also like Doxygen) * offer links to Wiki, bug-tracker, repository browser etc
I particularly like trac http://trac.edgewall.org, which builds a nice Wiki, Bug tracker and project planner on top of a Subversion repository.
One quibble: the term "Guru" sounds arrogant. I'd try and be a little more humble about leaving software in decent working order. I don't think ex-colleagues will use the term "guru" when they struggle to make sense of things.
> One quibble: the term "Guru" sounds arrogant. I'd try and > be a little more humble about leaving software in decent > working order. I don't think ex-colleagues will use the > term "guru" when they struggle to make sense of things.
I think Mr. Dent means that being the guru for a system is being the one person who is the source of all knowledge on that system. By documentating the system well, one can retire that status.
The only drawback to this approach I see is that instead of becoming a novelist you become a writer of many, many short stories and keeping all of those little different items can become as labor intensive, if not moreso, than having one large 'novel'. For my own sanity if I had documentation in this many different places and formats I would go one step further and create something ( a small set of python scripts in my case ) that pulled all those disparate sources of knowledge and put them into one place so I could check that one place from time to time and make sure everything was up to date.
I would still work on keeping only the local pieces up to date and just use the system to generate the overall docs. Personally I hate having to flounder around between the readme, code comments, the wiki, back to code comments, back to the wiki, back to the code comments, etc. just to get an overview of how the system works. Not to mention that if you keep updating these things piece-wise it is very easy to get into a state where the documentation contradicts itself all over the place. If they conflict,do I believe the code comments or the readme? Generally the readme would be the most up to date, but wouldn't you think the code comments would be more accurate, since they are more local?
That overall document can help you ensure consistency as you go and for somebody brand new it may be more helpful than having to send them to three or more sources. Personally when I take on something new I like to get as high a level picture of it as possible and if the pertinent documentation is gathered in one place, that lessens the amount of leg work I need to do to get familiar with the system. Having to go between several different information repositories slows me down and makes me grumpy, too.
> That overall document can help you ensure consistency as > you go and for somebody brand new it may be more helpful > than having to send them to three or more sources. > Personally when I take on something new I like to get as > high a level picture of it as possible and if the > pertinent documentation is gathered in one place, that > lessens the amount of leg work I need to do to get > familiar with the system. Having to go between several > different information repositories slows me down and makes > me grumpy, too.
I agree that having too many places for documentation is more of a burden than a help. Most likely, one or more will be come outdated and conflict with the others. I think that comments in the code are for low level detail of the actual code implementation and a higher level wiki with a drill down structure makes the most sense. A folder full of Word documents is what I am very familiar with and that just plain doesn't work. They end up being a disparate set of documents that don't tie into each other and are merely bread-crumbs to understanding the full and current state of the entire system.
A wiki is a living document that everyone owns and maintains and facilitates (and encourages) links to other living information.
> Wikis are good, I'm a big believer. They work well > with other link-friendly systems. Your issue-tracking > system and repository should make it easy to copy stable > links to embed in wiki pages.
Here is a critical voice. Wikis are increadibly bad for all kind of offline work. That's why I use static HTML for system specification and code documentation both for my private as well as customer projects ( as long as the customers don't demand Word ). I would really be pissed off when e.g. the whole Python documentation ( as was planned by some in the community ) would be moved into a Wiki and I couldn't use it when being disconnected from the Web. Also versioning of software documentation is a virtue hardly ever found in Wiki communities. If some customers A and B are using a systems spec for a certain version of their software I don't want to force them to inspect the edit history of the Wiki to find out whether they use the same document. I guess one can control this by advanced Wiki administration techniques but this is just additional overhead and becoming a systems administrator for just maintaining the docs of a small SW project is not really agile ;)
> Here is a critical voice. Wikis are increadibly bad for > all kind of offline work. That's why I use static HTML for > system specification and code documentation both for my > private as well as customer projects ( as long as the > customers don't demand Word ). I would really be pissed > off when e.g. the whole Python documentation ( as was > planned by some in the community ) would be moved into a > Wiki and I couldn't use it when being disconnected from > the Web. Also versioning of software documentation is a > virtue hardly ever found in Wiki communities. If some > customers A and B are using a systems spec for a certain > version of their software I don't want to force them to > inspect the edit history of the Wiki to find out whether > they use the same document. I guess one can control this > by advanced Wiki administration techniques but this is > just additional overhead and becoming a systems > administrator for just maintaining the docs of a small SW > project is not really agile ;)
Interesting points. I have to say that none of these concerns apply to the average in-house IT shop. When things are offline, it's either the case that no one is working anyway or the issue is being addressed and people do other things. Rarely do you have mutli-version in-house systems.
The versioning concept is a good point, in general though. Because a wiki is not a specific piece of software but rather a class of software products, there is no reason a wiki could not provide a version attribute to an article that could be used by the reader to filter info. I don't see any need for advanced administration techniques. In terms of offline storage, I don't see any reason why an extract of the wiki could not be stored offline in HTML form. The live data aspect of the wiki is lost, of course. Perhaps stable extracts for stable versions of the software would make sense.
> The only drawback to this approach I see is that instead > of becoming a novelist you become a writer of many, many > short stories and keeping all of those little different > items can become as labor intensive, if not moreso, than > having one large 'novel'.
If short stories are indeed that, and larger than just a method's doc, then using Doxygen allows you to put them in their own file. Say you have a single header file containing a @page directive. This text file will be checked into svn and so you now have a URL for that file which can be put into any issue-tracking system, wiki or other documentation you like. Seems like a good way to track stories to me ;-)
If you are following agile practices and want customer stories then this is a very low-tech way to record them and you can have a hyperlink to the stories from within any code, that works in the doxygen output..
With regards to method and class docs, the closer the documentation is to the products it describes, the more chance it will be updated.
That is one of the reasons I really like the ability in Doxygen to have the method documentation immediately precede the method (good for C++, irrelevant in Java and Python).
By writing the remaining bits of the "programmer's guide" also in Doxygen, it is textual and so nicely compared with version control diffs and can be included right there in your IDE projects.
BTW a useful language for sketching call chains, little box and arrow diagrams I use is the DOT language, used by Doxygen to generate its diagrams but also able to be directly included in Doxygen comments. As the included bits of DOT are textual, they too nicely diff and survive VCS merges.
http://www.oofile.com.au/files/MouseMovesDOTExample.png shows the rendering from the source below (download from http://www.oofile.com.au/files/MediaFood-MouseMoves.dot) digraph untitled { node[shape=box]; /* default */ "docWindow\nDrawingCanvas_MouseMove"->"docWindow\nHandleMouseMove"; "docWindow\nDrawingCanvas_MouseDrag"->"docWindow\nHandleMouseDrag"; "docWindow\nHandleMouseDrag"->"docWindow\nUpdateMouseLocationForRulers"; "docWindow\nHandleMouseMove"->"docWindow\nUpdateMouseLocationForRulers"; "docWindow\nDrawingCanvas_MouseExit"->"docWindow\nUpdateMouseLocationForRule rs"; "docWindow\nUpdateMouseLocationForRulers"->"GraphicRuler\nUpdateMousePositio n"; /*new defaults for comments */ node[shape=plaintext]; edge[style=dotted]; "GraphicRuler\nUpdateMousePosition" -> "DrawPicture to draw\nruler & dashPic"; }
> Wikis are increadibly bad for all kind of offline work. I don't know of any that can be updated offline and merge changes, out of the box.
As a reference source, some engines make it relatively easy to publish part or all of the wiki to an archive either in PDF book form or as a browsable website, looking like the original (eg: twiki).
As a wiki is a collection of text documents, there's no reason why you couldn't have the entire wiki under version control with a merging VCS and actually run a local copy on your machine. (Probably easier with a Unix-based OS ;-)
TWiki, in fact, already uses RCS for internal version control and being able to compare changes is a major benefit. I'm not sure how this would fit with trying to merge a local copy.
http://www.wikimatrix.org/ allows you to compare many different wiki engines and has a Choice Wizard to guide you through selection.
> > Wikis are increadibly bad for all kind of offline work. > I don't know of any that can be updated offline and merge > changes, out of the box. > > As a reference source, some engines make it relatively > easy to publish part or all of the wiki to an archive > either in PDF book form or as a browsable website, > looking like the original (eg: twiki). > > As a wiki is a collection of text documents, there's no > reason why you couldn't have the entire wiki under version > control with a merging VCS and actually run a local copy > on your machine. (Probably easier with a Unix-based OS > ;-) > > TWiki, in fact, already uses RCS for internal version > control and being able to compare changes is a major > benefit. I'm not sure how this would fit with trying to > merge a local copy. > > http://www.wikimatrix.org/ allows you to compare many > different wiki engines and has a Choice Wizard to guide > you through selection.
Andy, can you please show me one Wiki, yet available on the net, providing software documentation, that can be used offline by a user like me, who does almost all private work using a notebook that is disconnected at least 50% of my working time? I don't mention future prospects or technical possibilities but things that are working right now.
BTW I wonder about your question. The wish for losing "guru" status seems to imply that you are not willing to do maintenance for your project. But either it is usefull and important enough to many people that they will care independently or no one cares at all if you cancel. There is also just a limited amount of attention that can be spent to anything. If it is your primary goal to attract other programmers doing work in your own project High-effort about anything may be recommended. Right?
> Andy, can you please show me one Wiki, yet > available on the net, providing software documentation, > that can be used offline by a user like me, who does > almost all private work using a notebook that is > disconnected at least 50% of my working time? I don't > mention future prospects or technical possibilities but > things that are working right now.
Didn't he point to TWiki as one?
> BTW I wonder about your question. The wish for losing > "guru" status seems to imply that you are not willing to > do maintenance for your project. But either it is usefull > and important enough to many people that they will care > independently or no one cares at all if you cancel. There > is also just a limited amount of attention that can be > spent to anything. If it is your primary goal to attract > other programmers doing work in your own project > High-effort about anything may be recommended. > Right?
You seem to be assuming that the project in question is some sort of open-source project or something. I'm not claiming to be any better, because my assumption (until reading your posts) was that the project in quesiton was for something done in a closed shop.
From my perspective, a wiki is a very good tool and I think it would be even for a commericial software product. However, contrary to what you are implying, I do not see a wiki as being a good way to produce public documentation. I see it as a tool for communication inside the organization. It's not documentation per se, but a way to explain how things work internally e.g. what systems are running on what boxes and how to troubleshoot a particular piece of software (in-house or otherwise) and the nitty-gritty details of how things work.
So in short, I don't see a wiki as replacing the documentation for a system. I see it as more of an augmentation of that documentation. It would be nice if the wiki could generate that public documentation, though.
> Andy, can you please show me one Wiki, yet > available on the net, providing software documentation, > that can be used offline by a user like me
Sorry, I can't - nothing public.
However, http://twiki.org/cgi-bin/view/Plugins/PublishContrib is the tool we use to publish part or all of the project webs for CSIRO twiki's used by geologists and other scientists taking laptops into the field. It really does work to give you a usable offsite reference copy.
In terms of something that allows you to edit offsite and trivially merge, no I don't know of an answer. A project I am keeping a keen eye on (and wish I had time to contribute to) is the GroupEdit RFP from the Tidbits publishing company:
> BTW I wonder about your question. The wish for losing > "guru" status seems to imply that you are not willing to > do maintenance for your project.
Not my question - I just thought it was a good question to answer. If you re-read the first post you will see the origin ;-)
re losing guru status, James Watson was bang on - being known as the guru for a project can be an uncomfortable honour, when you're talking about an inhouse project like the original author of the question.
Being the visible figure in an open source project is of course an entirely different matter!
> However, > http://twiki.org/cgi-bin/view/Plugins/PublishContrib is > the tool we use to publish part or all of the project webs > for CSIRO twiki's used by geologists and other scientists > taking laptops into the field. It really does work to give > you a usable offsite reference copy.
Thank you! This is really helpfull.
> re losing guru status, James Watson was bang on - > being known as the guru for a project can be an > uncomfortable honour, when you're talking about an inhouse > project like the original author of the question.
This matters is more political than technical and won't be resolved by more documentation even when some managers believe this. The only way to lose guru status in this respect is to use the guru status in the strict sense of the word i.e. teaching people.
> Being the visible figure in an open source project is of > course an entirely different matter!
Yes, I've misplaced your question into the CEDSimply project context you mentioned some time ago.
> > re losing guru status, James Watson was bang on > - > > being known as the guru for a project can be an > > uncomfortable honour, when you're talking about an > inhouse > > project like the original author of the question. > > This matters is more political than technical and won't be > resolved by more documentation even when some managers > believe this. The only way to lose guru status in this > respect is to use the guru status in the strict sense of > the word i.e. teaching people.
Absolutely, however, in my experience, it has always been the case that people will forget what they are told until they need to use it and often even after that. Instead of answering the same questions dozens of times, I'd rather write up some wiki pages. As the consumer of the documentation, I prefer the wiki format to trying to remember which Word document contains the magic piece of info that I am looking for and whether I am looking at an up-to-date version. It's really (in my mind) the best format to-date for team, department, and project esoterica. In other words a great way to publish info that no one can be expected to figure out on their own.
Previous Topic
