5

UPDATE: I've gotten a lot of feedback, but no info on what percent of time people spend on docs. To keep it simple, say the docs are for developers and peer reviewed; meaning the peer understands how to do it, and the comments are more for the what is being done, not how to do it from scratch; which in my case is the request, just don't think the request is common.

Been working a project for 2 months, and it's done. When the project started, documentation was not a requirement; focus was "get it done." So, all the sudden there's an interest in creating documentation for the project... that's 100% turn-key, meaning that someone with no understanding of anything, would be able to do everything required to duplicate the work done.

In case it matters, the project was a data profiling, extraction, transformation, and loading themed. Meaning I was given sets of data, a final state of the data -- and figured out all the issues/solutions to make that happen.

Just wondering if anyone has seen stats on the average percentage of time take to write docs.

(Have questions/feedback, just comment -- thanks.)

| improve this question | |
  • I would be surprised if anyone keeps statistics on this. I would be further surprised if such a number were consistent from project to project, or from organization to organization. – Marcie Jan 25 '11 at 20:49
  • @Marcie: It'd be possible for me to create stats based on past projects, meaning I log my time regardless of if it's require or not. Just though there might be a rule of thumb, or real numbers. – blunders Jan 25 '11 at 20:57
5

So, all the sudden there's an interest in creating documentation for the project... that's 100% turn-key, meaning that someone with no understanding of anything, would be able to do everything required to duplicate the work done.

Do they actually want developer or user documentation? To me it sounds like the former, but it is quite unclear.

I would say this is a completely unrealistic expectation. Of course depending on what "no understanding of anything" actually means: a person with no programming background? or one not experienced in the specific language / platform / domain? Or ... ?

Anyway, writing such detailed documentation is a huge task, much better suited for a professional document writer than a (however experienced) developer. And its result would quickly get obsolete - the more detailed the docs, the faster it gets out of sync with the code.

| improve this answer | |
  • 1
    "completely unrealistic expectation" yes, I agree -- and it's based on the fact they've never created docs like that. Anytime I hear "I want everything" -- all that says to me is that the person has no idea what they want/need. "the more detailed the docs, the faster it gets out of sync with the code" great point. – blunders Jan 25 '11 at 13:31
2

It's impossible to answer because the meaning of usable depends of your specific case. Giving us more precisions will make the question too localized.

Therefore I can't only answer that such stats doesn't exist and if they exist, they are not reliable.

To address that issue, I usually build documentation on demand after I did the basic stuffs. Sort of lazy loading for documentation.

| improve this answer | |
  • +1 Agree that such stats don't exist, and in fact in my case the request just is a little off the wall... since the the client wants anyone, to be able to do everything, and their not even playing on testing the docs. I've been writing docs and procedures off and on for over 15 yrs and never gotten a request like that... :-) – blunders Jan 25 '11 at 13:09
  • 1
    @blunders: in that case, they should figure out how much, not you. – user2567 Jan 25 '11 at 13:17
  • +1 That was the approach I took, didn't work. They just want it done, which is what I'm going to do -- meaning I'm just going to put a lot down, and guessing they'll be happy -- regardless of if it's of any real use... – blunders Jan 25 '11 at 13:48
2

there's an interest in creating documentation for the project... that's 100% turn-key, meaning that someone with no understanding of anything, would be able to do everything required to duplicate the work done

Unfortunately that level of precision means that your project documentation needs to include minutes on all of the decisions and trade-offs that were made, by whom, and why that person's decision was authoritative: this is very hard to reconstruct ex post facto. Fortunately that level of precision is almost certainly unnecessary, because your project has already been completed: no-one ever actually needs to duplicate it. Even in scientific computing where people need to be able reproduce each other's results, we're allowed to use each other's tools to help.

So I think the answer is to find out what the real documentation requirements are, then to follow your usual estimation routine to work out how long it might take to fulfil those requirements. On subsequent projects, you can plan for the documentation as part of the project work and for it to take less time because you don't need to reverse-engineer the project at the end.

| improve this answer | |
  • +1 I've been trying to figure out what the real requirements are for weeks, requested to do a small subset of the docs and get back -- and only got additional specs on the docs that had nothing to do with the subset of docs I created. Oh, well... And I agree it's not needed. – blunders Jan 25 '11 at 13:29
  • FYI, the company is in fact a biotech - and believe their trying to apply their rough ideas of how to document an experiment with software development. – blunders Jan 25 '11 at 13:35
  • 1
    @blunders: point out that the goals of the scientific method and software project management are different. Experiments must be repeatable: software projects must avoid repetition. – user4051 Jan 25 '11 at 14:08
  • +1 Yes, I've pointed this out to them, didn't work. Oh, well -- guess the lesson is to get in writing if documentation is required, and if so, what it's role will be. Just never had anyone ask for docs at the end of a project. Meaning if they're required (which I was told the were not at the start) -- makes more sense to write/test them as the code is being done, not after the fact. – blunders Jan 25 '11 at 14:28
2

"all the sudden there's an interest in creating documentation for the project... that's 100% turn-key, meaning that someone with no understanding of anything, would be able to do everything required to duplicate the work done."

This takes a LOT longer than you think!

Don't underestimate this. The type of documentation you are referring to requires a decent technical writer and should not be written by someone who is 'close' to the code. You need an outsider view of the system.

It needs to be written, reviewed, revised. It needs to be tested against the software. It needs to be maintained with the software. Maybe it needs translation. If you don't get it right then it will not be used. It's a significant percentage of the time it took to write the original software.

| improve this answer | |
  • +1 Agree -- guess I'm just asking to make sure I'm not out of touch. – blunders Jan 25 '11 at 13:25
1

It all depends is the simple answer I'm afraid, but do not underestimate it.

Start by listing out the docs they want, and sticking a large number beside it, I don't know, say 5 days.

The try and bullet point everything each doc will need, and take it from there.

| improve this answer | |
  • +1 Agree, it's the approach I took, and did one round on a small sample. Didn't work, they just added additional off-topic requirements, and gave no feedback on the sample. My approach is now just to give them a lot of stuff, and call it a day. Meaning I don't think they're going to look/use any of it, and just want a mass of docs to "say" they covered their a**. – blunders Jan 25 '11 at 14:36
  • lol!! customers.... gotta love 'em! – ozz Jan 25 '11 at 14:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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