Posts Tagged ‘document’

How to create your design documents

Tuesday, May 11th, 2010

Please read previous blog How to write document in agile WoW before reading this.

If you decide and know the value of your document, now it comes to how to create your design documents.

One portal with good structure

First u need let people to find the document easily, good practics is to put one big button or something in you web front page. using mvn site is also really recommened way

Then you need a good structure for the documents, this is very tricky part like customer document, fortunately there are lots of nice opensource project you can follow, see example from maven and dixia

image image

Generally we need have

- Getting started serious (tutorial, demo, screenshots, introduction slides, establish environment, download, feature list ..)
- System archicture description (deep understanding on complex solution and architecture)
- Post documents from project (new features introduction, new component, new domain ..)
- Reference (link to javadoc, test case, API, FAQ)

Tags: , , ,
Posted in Agile, document | No Comments »

How to write document in agile WoW

Tuesday, May 11th, 2010

image Back to 2003, when I first present agile manifesto to management group, most of managers think agile will have no documents. Unfortunately after 7 years, still some (not most of ;-) , treat agile equals no document, and most of the company are struggling how to write document in new agile way of working now.

In Agile domain, no one said no documents, it suggest to look into the value of document.

Most of document (like process) are generated by fear.

  1. people will leave, how to keep this competence when they leave ?
  2. solution is complex, how to let people know it after long time ?
  3. review by other sites, without document, how to do it remotely ?
  4. …

I try to answer some questions above

  1. How many people do you have which leave in last 3 years ? if lots, then it is HR problem. and compare to the cost put on documentation, I more prefer to have more automated test case.
  2. Can you ask the architect team to simplify the solution (I don’t mean the whole 3G network) , if not, ask them it is the requirement. Most complex solution will cause more problem than expected in long term
  3. Can you avoid remote development ? if not, ask them to avoid.
  4. …

Ok, surely there are several cases we still need document besides customer document.

System Architect Document is most useful document, and please keep it to date, my suggestion in previous blog is to make it automation as well.

Introduction slides shall be provided to let people know what it is quickly

If key learning, tricky issues are better to write wiki document.

And without documents, how to handle the knowledge, here are some tips

- Move most of document into test case and stay with the codes like javadoc, since it can be automated with CI and information is update to date
- pre-document (detail design) shall be changed to f2f workshop in the beginning, and summarize importnant issues (if want) in the end.
- architect transfer shall be hands-off
- avoid model as much as possible, seldom I see model works (competence is also issue)

(quick blog, wait for comments)

BTW: how many documents stored in your document repository are still useful ? 10% ??

Tags: ,
Posted in Agile, document | 2 Comments »

documentation into automation to improve your agile way of working

Tuesday, May 11th, 2010

Probably most of company had already established their CI system using hudson to improve the automation from old crontab building system after their agile deployment.

image And this is the key for the start of your agile way of working.

- compile finish, unit testing finish
- yeah, package is generated from CI
- and if lucky, your integration and system testing are working well in CI
- great now it can be released automatically from CI

But don’t you miss something ???

Documentation are not in CI , this is actually always a headache in DONE for each iteration spring as well

Normally document part is in seperate group (technical writer), then they need input from the team and finish according to their plan.

Furthermore, documentation system (tag tool) is very difficult to integrated into CI.

We need improve this area, recently I notice one good approach The ‘Continuous Integration with Hudson’ book build process, they write book in xml files and using hudson to generate PDF/HTML directly.

Probably we can use this idea as well.

Surely for the javadoc (API) level document shall be no problem.

Tags: , , ,
Posted in Agile, document | No Comments »