How much percentage of your day would you like to spend on writing Documentation as Software Develoeper ?

Question

How much percent of time do you spend on documentation per day as software developer and ideally how much time should given to documentation ?

Answer 1

Very little of my time is spent documenting code and most days the "percentage of time" is zero.

This is kind of an "old school" question. Time and experience have proven that code documentation is not the best use of your resources. Instead, the code should be written to be readable from the start - it should be self-documenting. Documentation, used sparingly, can be applied in just those places where the underlying logic cannot be made clear enough via the code itself.

If you want to learn more about the roots of this idea - and how to create self-documenting code - then the reference work is Robert C. Martin's "Clean Code". For a deeper analysis of the art as a whole (but less focus on coding standards and documentation) I'd also strongly suggest that you get the "Bible": McConnell's Code Complete 2.

Update: Here is an example of what I am talking about. Let's say that you want to have a client verify their demographic information (name, birthdate, gender, email) in a web app.

Old school developers might create a page "Verify.aspx" where the Page_Load pulls initial client demographics from the database and places the field data in UI controls. In the submit response, they might apply some business logic ("Ensure that a newly entered EMail doesn't conflict with another record's email", "check that firstname is not empty", etc.) and then populate database parameters, fill a SqlCommand object with a SQL insert statement and execute it. Yuck...but definitely how most code I've seen operates. You're likely to be tempted to explain each of these steps so people know when you've switched from DB logic to Business Logic to UI logic, etc. (e.g. "The session must have a CustomerID set").

Now, if your code is properly segmented - into database, business logic and UI layers - and you have named things in a clear and obvious way then you'll find the code itself to be easy to read. Here is (pseudocode) for how I handle this task in one of my projects:

protected void PageLoad()
{
  using (var customerLogic = new CustomerLogic(sessionData))
  {
     Customer customer = customerLogic.Fill();
     if (customer.Status == fcError.mbInvalidCustomerID) 
       throw new Exception("Invalid customer ID in validation request...");
     CopyCustomerDataToUIFields(customer);   
   }
}

protected void SubmitHandler()
{
  var customer = new Customer();
  if (!CopyUIFieldsToCustomerDataObject(customer)) return;
  using (var customerLogic = new CustomerLogic(sessionData))
  {
     customerLogic.Save(customer);
     if (customer.Status == fcError.mdDuplicateEmail)
     { 
       ErrorMessage.Text = "This email is already in use by the client having an ID of " + customer.SigninID;
       return;
      }
   }
   Response.Redirect("Home.aspx");
}

protected bool CopyUIFieldsToCustomerDataObject(Customer customer)
{
...
}

protected void CopyCustomerDataToUIFields(Customer customer)
{
...
}

Truly, what is there to document? Are you really going to put in a comment like this:

 // Copy all of the customer data in the customer object to the UI fields
 CopyCustomerDataToUIFields(customer);

No! Because your naming conventions are well thought out and your code is all at the same level of abstraction, the documentation is completely redundant.

If the next developer wants to know more about the Business Logic, they'll open up the CustomerLogic class - which is an entirely separate and self-contained world. This kind of segmentation lets the developer work at a level of abstraction wherein the logic of their task is obvious. In the end, the need for documentation falls dramatically if you follow descriptive naming conventions and avoid mixing code that implements multiple levels of abstraction.

One last thing: segmentation also facilitates unit testing as well. This code is an almost straight paraphrase of code in a project I am working on now so this isn't just theory.

Answer 2

I used to spend one fourth of the time to finish documentation, recently, we are starting to try agile process, we spend much less time on documentations, say about half an hour to an hour a day. But we are not sure that will work out eventually.

Answer 3

I know it is bad practise but I hate writing documentation, I only do so when users request it.

Answer 4

While there is value in documentation, signatories of the agile manifesto value working software more. So do I. Thus, to me, documentation should be written just-in-time, and just enough. In other words, write documentation as late as possible and keep documentation just simple enough, but not too simple.

Answer 5

You write documentation to explain whatever cannot be inferred from the code alone. It takes as long as it takes.

Answer 6

Most of the time people will tell you '0 second'. But I think there is an exception for companies doing product for other developers. For example the documentation of the components of Telerik's products are very valuated by every developer. There is no way we can find how to do stuff with these components reading only properties and methods name.

So as always "it depends".

Answer 7

I only really document my code when I revisit it after a long absence. Usually I have completely forgotten what I was thinking when I wrote it. If I cannot instantly understand the code then I add more documentation. This works for me as I only write the essential documentation.

My experience is that whenever I write detailed documenation it is usually out of date by the time anyone might read it. In general, in never gets read.

Answer 8

Preferably zero! Ideally, I would like to verbally delegate this task to a tech savvy documentation team, who can just look at my code and insert comments, then create documentation. It sucks that we don't have this luxury. Hence I end up spending, give or take, %5 of my time...

Answer 9

I tried to write the so called self-documenting code, to avoid code documentation. Well, there is no such thing as self documenting code. You can't easily deduce class responsibility or details of design of implementation by just taking a look to the code, no matter how careful you are on naming. I never succeeded to write such code and never saw such code written by others.

So I tried to document the code, putting only the strict information to allow somebody else (or me, some time after that) to understood the purpose of the code in an easy manner. Never measured the proportions... but it doesn't take so much when you are doing it as code comments.

Answer 10

If it's documentation for the users, like a manual, that is not the job of a developer/programmer. When we try, it generally doesn't work out too well as we either assume too much prior knowledge of computing, or go into excessive depth.

If it's documentation for other developers, then this should be updated as required. We use an internal Wiki for this, and it covers things that fall into categories such as 1) technical info on how things fit together, 2) brief summaries of systems and contact info relating to them, 3) various hacks that the admin tools can't cover yet, 4) links to useful tools and sites, and 5) loads of other scraps that wouldn't mean anything outside of the team. So, I'd say I spent up to 1/10th of my time doing the second kind of documentation, and I think that's a reasonable amount.

Answer 11

There are 3 primary forms of documentation:

1) Design documentation. Hopefully you write a spec before writing the code, so there is a clear description of what the code is meant to do, and how it is intended to work and be used.

I find that for anything other than the most trivial features, any time spent doing this usually reduces the overall time spent on a task and the number of bugs that emerge. So while I don't enjoy it as much as coding, it's worth doing.

2) API documentation. If anyone (including yourself) is ever going to call a method, then it saves a lot of time and improves code quality if the method is documented. Many simple methods can be self-documenting using good naming, but often little pieces of information can save a lot of time (classics are "index": is it zero-based or one-based? pointer/reference: is it legal/safe to pass in a null?)

I find that any code that I don't use on a daily basis is usually mostly forgotten within a couple of weeks, so API documentation significantly improves productivity overall by allowing me to quickly confirm the parameter requirements and operation of a method, rather than having to go and work it all out form first principles. With tools like intellisense you often don't need to look at the source code for the API you are calling. Comments on subtle but important features (like index/null usage) that only take a few seconds to write will save days of debugging far more often than you might think.

3) Code documentation. This is where you comment small blocks of code within a method to describe what the block does. There are a couple of important cases: (a) a summary (e.g. "write the preferences to an xml file" might summarise a 10-line block of code). This allows programmers to skim-read the "highlights" of a method and zone in on the important bit quickly, instead of having to read the whole method carefully to work it all out. (b) a comment describing why you did something a specific way (e.g. "this must not be deleted yet because object X is still using it", or "Calculate the result using bitwise operations as this is a time-critical section of code"). This is essential to stop a programmer from refactoring this code without realising that there might be unintended side effects to their changes.

Again, this is vital to allow programmers to understand the high-level flow of an implementation quickly, and to avoid people misunderstanding why code is written as it is.

So my answer is:

You shouldn't spend any time "on documentation". You should spend all your time writing good, maintainable code. Documentation is part and parcel of that. IMHO it's not a separate activity, and it's not optional.

Answer 12

Real programmers don't document. If it was hard to write, it should be hard to understand.

Answer 13

I find the documentation that is most useful to me (and that I subsequently spend more time writing) is documentation that explains why something was done not what was done. This is especially true when you have to choose between several different possible methods and some of the possibilites that spring to mind immediately will not actually allow you to implement your requirement.

I've seen so many people through the years change stuff they didn't like becasue they preferred a different method without ever understanding why the other method was chosen in the first place and Blam, break something critical. I often add a reference to the specifc project in our Project Management system in a comment, so that the people maintaining can easily look up the requirement at the time the code was written. This helps prevent people from inadvertently changing that requirement to meet a new related requirement but one which should not overirde the first.

Users, as you know, will often ask for conflicting things without realizing they would be in conflict with an existing requirement. Being able to say to them, if I do that then this other requirement won't work anymore has saved me more than once from breaking something really important to accomodate a small change a year down the road. It's a lot easier to do that if you know exactly where the original requirement came from.