12

Where I currently work the general approach is -

avoid documentation as much as possible

Only document if a different team will need it

just for clarification, I don't mean code-documentation - this we do, I mean all the documentation surrounding the design process - if it's UML or DB Schemas, class diagrams and word documents with specifications and the likes.

I will list my Boss' reason to not document:

  1. it's time consuming - focus on implementing
  2. if design change - then the documentation should change, double trouble
  3. in the end you just get hundreds of pages nobody wants to read, and nobody really edits so by time it will get out of date
  4. Its a pain - nobody really wants to do it

Now I realize we do work faster, but I also remember the time getting here and diving straight to some old code, not understanding anything.

Actually, I still don't get most of this old code, and sometimes when I get in I see many patches from different developers trying to make small tweaks.

I really think lack of documenting promotes these kind of patches and lack of system understanding in a broad sense.

my question is:

How can we balance documentation so that we will promote continuous knowledge among the team and still be fast and efficient?

6
  • I have the same problem at my place - except my team doesn't even write code comments!
    – MattDavey
    Commented Feb 2, 2012 at 14:54
  • 1
    Do they at least document the minimum requirements and specs? If not, how do you know you've coded the right thing if there's no requirements to compare the finished product to? Commented Feb 2, 2012 at 15:17
  • especially with modern languages the technical documentation is much much more important then documenting the code. code should be self explanatory.
    – AK_
    Commented Feb 2, 2012 at 17:41
  • Whereas it is indeed a good idea to avoid too much documentation, your boss just does it for all the wrong reasons. Commented Feb 2, 2012 at 17:42
  • Can you give an idea of the industry that your company is operating in? Some industry have legal requirement on how minimum level of documentation required.
    – tehnyit
    Commented Feb 3, 2012 at 15:05

5 Answers 5

6

I've found ANY documentation is better than NO documentation. The appropriate amount is usually determined by the amount of time we have to do it, or by how much we hate support phone calls and emails.

It appears that your current team members have some unrealistic expectations of their memories, or they are ashamed of their writing skills, and are unwilling to practice.

I realize I am in a minority (English major who got into software engineering in graduate school) here, as I don't find documentation as a chore. It's a valuable professional tool. I may not find writing as difficult to do as some of my coworkers, but that's mostly because I have more practice at it. I don't consider a project finished unless it has documentation, and I usually write it for purely selfish reasons: so I can give people something to read instead of taking phone calls and emails, or so I can remember what we were talking about last month, or so I can refer to how I did something if I need to support it in the middle of the night.

The best way to approach documentation is to write it AS YOU GO, exactly like writing test code. It's amazing how a few pre-written templates (with headers, stubs of code, etc.) can make documentation easier and faster to do. This way you can capture change as it happens, and you have less ground to cover over time. You are more efficient this way, since you can refer to documentation as you need it, and you change it along the way. Doing so in a wiki, for example, makes updates easier, and you can avoid document version issues if the latest and greatest is always online in the same place, and you can just send links to people who need to read it.

If you spend a little time documenting, you will ALL work faster, especially when someone new joins the team, since they won't have to spend all that time figuring everything out. Figuring stuff out is a fun part of our jobs, but it's not fun when you have to do so in a hurry to fix production. We'd all save a lot of time if we all wrote a couple more notes.

Does your team have the same issues with testing, or writing test code? If not, this will be an easier sell.

Your documentation is useful in many ways:
1) To you, right now, and to your coworkers, as you work on the project.

2) To your customers. Having documentation (including diagrams) that you can show users makes discussions in meetings easier, especially if you are discussing complicated systems. Even if the documentation is incomplete, it's a place to start from.

3) To the people who will inherit your work (which may even be you, in three years). Many of my younger co-workers think they'll remember stuff forever. I know I won't remember it past this week if I don't write it down. Having documentation saves you from having to spend half a day to remember how you structured something, and having to figure it all out again.

4) To you and others, if the situation gets political or contentious. As someone who takes notes in meetings, to keep myself awake and fight boredom, I have often been the only one with the written version of a decision. The person who wrote it down wins the dispute. Remember this the next time someone says "Remember that meeting we had this past winter in conference room 4, when we were going over X? Fred was there, and who's that guy from Accounting?"

2
  • 1
    +1 for point #3. My own personal documentation has saved me sooo many times.
    – Brandon
    Commented Feb 2, 2012 at 16:42
  • I throw mine in the same git repo as the code, usually in Markdown (occasionally in LaTeX, when there's a bit of maths involved).
    – TRiG
    Commented Aug 8, 2018 at 20:47
4

At my last few employers, we've had a "development" wiki. Significant chunks of functionality (new import / export feed, how the security subsystem works, where does the system store uploaded documents, etc.) all get documented on there. It's usually a mandatory item to be completed before the code review step. There's usually a bit of resistance to it at the beginning, but once someone needs to go look up a bit of information and it's on there, you've got another convert.

The nice thing about having it in a wiki format is that you're much less inclined to do all the pretty Word formatting and such and just write out the real information you need to save. Most (if not all) wiki packages will allow you to upload documents or images (like Visio UML diagrams, or UI wireframes), so you can have visual pieces as well.

Like most things, I think you should aim to do the minimum amount that could possibly work. That's not the same thing as none though.

2
  • This is a great suggestion. Some wiki allows for the contents to be exported to a .rtf document. Almost perfect for the PHB.
    – tehnyit
    Commented Feb 3, 2012 at 15:07
  • We use XWiki, specifically for its ability to generate documents in PDF, RTF and HTML. Wicked good.
    – Jennifer S
    Commented Feb 3, 2012 at 16:28
2

You cannot escape allocating time to write proper documentation. Balance it however you wish depending on how much work you are given, but leave a good 15-20% of your time to document what you have done. Everyone on the team has to be on board with this, including your manager, otherwise you will only be documenting for the benefit of others and will get nothing in return. Documenting must be an integral part of your development process.

1

Documentation should tell you WHY you did something while you leave the HOW part to the actual code and WHAT part to the unit tests. Anything more is a pain. This is usually good enough for smart people who just want a starting point.

Also, don't forget to maintain an overall high level architecture of each big component of your code base. Makes it very easy to induct new team members.

Finally, whenever you add a wacky fix, link to your bug database from a comment - very useful.

1

Your boss is right don't print any UML documentation that nobody will read. What we do in our team is to navigate live in the model using class diagram views. The principle is to always update MOF, the UML model live from the code and let the class diagram only be a viewer of the model but not the model itself.

It works really well because all the complexity is done in backoffice at model level. I can refactor my project, write java doc or write uml documentation in the model. It is a kind of click and go. When you click you get the live documentation. If something is not clear then I open the class diagram and start playing with it. Delete from diagram classifiers, add new classifiers, zoom in and out, show association, delete association etc...The model is not changed because I do not create any new model information, I just use them.

It is really important to open the diagram of a package and be able to read directly in the class diagram a comment on what this class is supposed to be. What this method is supposed to do and what is the flow etc....

UML is great, really helpful but we should stop using Model Driven Devleopment in order to give more flexibility and more iteration at modeling/development stages. The class diagram is live updated from the code and documentation is always accurate and available just by a click. I will not mention a tool but if you use Java and Eclipse it is easy to find which tool I use :-)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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