1

I'm responsible for documenting a huge ERP - its being changed from an old language to .NET.

I'm the only one responsible for documenting ( and I'm doing it off-site - the developers' office is an hour's plane journey away). I've never worked directly for a software dev company before.

So noob questions and lots of them coming ...

Are just the code changes documented in each sprint in an agile development? Is anything else documented? The developers seem to think documentation is a waste of time. Who is the audience for these docs?

  • 1
    There are many kinds of documentation used in software development. What kind are you writing? Each kind has a different purpose, audience, etc. – Mr. Shiny and New 安宇 Dec 23 '14 at 14:54
  • Thanks. I am writing end-use documentation that also explains the business logic behind the programs, and also technical documentation for the developers. – Stefan Piskorski Dec 30 '14 at 14:46
3

In an agile project with a diversified team, there are two primary purposes for documentation. Both of them are detrimental to the software development process.

As Benjamin noted, there is documentation targeted at the users (both developer and non-developer level). These documents will focus on the functionality of the project and the interfaces which it provides to programmers of expansion and interaction with other programs. Since this project involves the conversion of an existing software to a new code-base, you should be able to find documentation of this type relating to the early version of the system. Starting with this existing documentation, you can append, adjust and prune the existing content to achieve a new document which thoroughly reflects the functionality and interfaces of the new code-base.

In addition to this type of documentation, you may be called on to document the agile programming process. In this role, you would record the state of the backlog at the beginning of each sprint; then document each programmers progress during the daily scrum meetings. Reasons behind the reordering of items in the backlog and details about impediments encountered by programmers during the sprint would be the bulk of your content in this kind of documentation, which would be targeted at the funding sponsors, giving them feedback on their return on investment.

Both of these documentation efforts are actually contrary to the standard practices of agile, as writing documentation before or during development is generally discouraged. The idea of agile is to write the product that the customer wants, one page at a time, with continual re-evaluation of direction after every page/sprint. There is no way to write documentation about what the final product will look like as it is growing organically. Likewise, it is harmful to write documentation about the software development journey, as such documentation ignites the blame game and thus impedes the programming practice of fail-often/fail-fast.

In my opinion, the documentation specialist should live about a hour's flight from the programmers but should live next door to the testing department. Only when each sprint closes and the finished code goes to testing, does your opportunity to learn its functionality begin. And only after that learning is complete, should you finally and hesitantly begin to put some user documentation down on paper.

...as for the documentation for the funding sponsor, they shouldn't need more than their bank statement to make their decisions. Trying to give non-coders enough insights into the coding process so that they can make intelligent decisions and "manage" coders is exactly the impossible task that agile was designed to avoid.

  • I've been keeping close to the testing since your reply, rather than inventing the wheel again - thanks again – Stefan Piskorski Jan 7 '15 at 15:27

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.