6 Replies - 576 Views - Last Post: 19 January 2015 - 01:57 PM

#1 lodui  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 2
  • Joined: 17-January 15

Documentation Strategies in Agile Environment

Posted 17 January 2015 - 01:34 PM

Hello. Recently I've joined a new career in a fairly large pool of developers. I've been asked to submit guidelines for the developers concerning how documentation should be handled and standardized for a new & large project.

I've been considering this since yesterday, and strangely, it's not as straightforward of a task as it sounded when I received it. The fact that it's a distributed team working in an agile environment in many ways is much more important. The person seeing your code may be in a different location makes it an obvious necessity.

The flip side of that is that in an agile environment, code and customer expectations are going to evolve over time, and excessive documentation over a test class which will get phased out would be fairly counter to the concept of Agile development.

What I've come up with thus far, is that while it's critical to document, the documentation should be fluid and terse. A class should explain what it produces or initializes, and a function/method should explain output.

In agile, as the code is refined over time, the documentation will be as well, to reflect changes as they're adapted fit the project.

Since I'm new to the agile development in practice(my last two jobs had 2-3 other developers), my question is if that premise is on the right track. Any wisdom would be appreciated.

Thanks

Is This A Good Question/Topic? 0
  • +

Replies To: Documentation Strategies in Agile Environment

#2 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10809
  • View blog
  • Posts: 18,468
  • Joined: 19-March 11

Re: Documentation Strategies in Agile Environment

Posted 17 January 2015 - 01:39 PM

What sort of documentation are you trying to deal with here? Are we talking about developer-facing docs about the codebase, or are we talking about customer-facing instruction manuals, or are we talking about documentation of design decisions (requirements, specs, etc)
Each of those requires different strategies.
Was This Post Helpful? 0
  • +
  • -

#3 lodui  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 2
  • Joined: 17-January 15

Re: Documentation Strategies in Agile Environment

Posted 17 January 2015 - 01:47 PM

View Postjon.kiparsky, on 17 January 2015 - 01:39 PM, said:

What sort of documentation are you trying to deal with here?


I'm referring to internal developer-facing docs, which may potentially be read by many devs, and QA's.

Thanks!
Was This Post Helpful? 0
  • +
  • -

#4 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10809
  • View blog
  • Posts: 18,468
  • Joined: 19-March 11

Re: Documentation Strategies in Agile Environment

Posted 17 January 2015 - 02:28 PM

QA's should be reading design docs - requirements, mostly, since that's what they're testing against. There's not much reason that I can think of for testers to be looking at code.

Developer-facing docs should live as close to the code as possible, for the most part - functions should have comments describing their behavior, what they expect by way of arguments, and what they produce as output, and especially any side-effects they produce. For documenting connections between classes and such, you can use something like Doxygen. Ideally, this would be kept in sync by either a cron job or a repo hook.
The issues list and commit logs are also great sources of real documentation, particularly if developers are in the habit of correlating the two. If every commit message references an issue, and you can trace back from issues to commits, then you have a lot of information about what code relates to what issues. If I can get this, I generally don't need much else. Unfortunately, there are many shops where commit messages are considered some sort of effete bourgeois affectation - these are usually places to avoid.
High-level commentary can be useful. This should live in a developer wiki. This might include things like style guide, known issues, local idiosyncracies, that sort of thing. This should be maintained by the developers, perhaps with some input from a writer. If devs are sufficiently motivated to keep this up to date, this can be a rich source of useful stuff, and usually completely impenetrable to people who aren't up to their necks in the code. This is fine, that's who it's meant for. This is only going to happen, though, if the environment facilitates it. If developers have management breathing down their necks, clamoring for features, then documentation is the first thing that gets "deferred" (permanently). In that scenario, you typically end up with a dearth of documentation, and eventually someone comes up with the clever idea of hiring a writer to repair this flaw, which of course only makes things worse.
Was This Post Helpful? 1
  • +
  • -

#5 CP3  Icon User is offline

  • D.I.C Head

Reputation: 5
  • View blog
  • Posts: 57
  • Joined: 21-October 12

Re: Documentation Strategies in Agile Environment

Posted 17 January 2015 - 09:54 PM

View Postjon.kiparsky, on 17 January 2015 - 09:28 PM, said:

Developer-facing docs should live as close to the code as possible, for the most part - functions should have comments describing their behavior, what they expect by way of arguments, and what they produce as output, and especially any side-effects they produce. For documenting connections between classes and such, you can use something like Doxygen. Ideally, this would be kept in sync by either a cron job or a repo hook.


I completely disagree with this. Comments should describe why, not how and the code should be self-documenting, meaning if you have to write a comment to describe it then it's too complex. Comments do not tell the truth because they are rarely updated with code.

The problem with pages of documentation is that it's out of date immediately after being written and ask yourself when was the last time someone consumed all of that?
Was This Post Helpful? 1
  • +
  • -

#6 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10809
  • View blog
  • Posts: 18,468
  • Joined: 19-March 11

Re: Documentation Strategies in Agile Environment

Posted 17 January 2015 - 11:22 PM

I think you're not disagreeing with me nearly as much as you think you are. In fact, I see very little disagreement at all.
Was This Post Helpful? 0
  • +
  • -

#7 Skydiver  Icon User is online

  • Code herder
  • member icon

Reputation: 5955
  • View blog
  • Posts: 20,409
  • Joined: 05-May 12

Re: Documentation Strategies in Agile Environment

Posted 19 January 2015 - 01:57 PM

I believe in self-documenting code, and any comments that exist are there to explain the "why" rather than the "what" or "how". If DRY is considered to be a good programming principle, it should also apply to documentation.

Anyway, check out the documentation for the code is this closed C# thread. In my opinion that amount of documentation would be great to have, but I am willing to live with 50% less. In that code, the "why" that stays unanswered is the use of goto's. There was nothing there that could not have been solved by using helper functions instead of goto's.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1