OT - Book about software project definitions and the pre-coding phase

[Josh Golden]

i lead a small development team (based on some of my posts that might cause
some people to choke themselves, but have no fear, i am NOT the lead
developer, the people on my team are great - i'm just the manager) for my
company. although we attempt to use good practices for development, we have
no real experience in documentation of a project _before_ it's coded.

Are there any great books out there on how to document a project before we
code. For example, i actually hear that some people write classes off of a
master document that lists all properties, methods, events, etc. We
basically just survive on notes, meetings, and the "code like hell"
methodology - which will kill us in the long run.

I have some great books on management, like the mythical man-month and
others, but I am interested in a book on documenting a software project
before the coding starts.

Thanks

[Richard Myers]

Hi Josh,

I appreciate that you have recognised your "problem" and have the energy and
committment to undertake further training to attempt to resolve it... but
are you serious?

Flag the books.... just go buy the skillset you need. Sack/demote your "lead
developer" if you have too in order to afford an SA. He/she is just an
imposter if they are prepared to lead a team with no solid architecture.

"Coding like hell" will just get you nowhere faster.

You need to identify a suitable methodology such as UML, and work from
there, but that will obviously require your "team" to learn the methodology
as well.

If you've "grown" the team into this situation then congratulations are in
order... but do yourself a favour and get the right people with the proper
skills doing the right job, right now. Dont diddle about with books as a
cheap substitute for a flesh and blood professional.

Software projects are like children, they require different people with
different skillsets at different stages of their lives, otherwise they tend
to grow up with all kinds of weird and wonderful disorders that make it
really hard for them to play well with others and make their own ways in the
world.

If all this sounds a bit harsh then dismiss it, after all its your future
not mine..... and the smart arse within me is saying "Thank God"!

;)

hth
Richard

[Josh Golden]

Richard, I appreciate the honesty of your post but you have to understand
where we're coming from. i'm not some great programmer who has 2 degrees in
technology. like many others, i drifted to IT after making some wrong life
choices (that's my assessment) and i'm here because i really like the stuff.
i'm a great dba but a mediocre application coder. i've been at this company
for a while and had the ability to hire some young people who also like to
code and collectively we make good stuff.

perhaps you're right that i don't need a documentation book, i need a uml
book. i can't take a week off to attend a class so i gravitate towards
books because i can read them in the car (not while driving), plane, beach,
bed, etc. what everyone in my group needs, scratch that, needed was to work
a year for some big company that has big documented projects so we could see
how it's done but we didn't. we're just collectively good software people
who missed some fundamentals and now at least have the smarts to recognize
that we want to do it better. i don't want to fire anyone.

thanks for your help on my datatable/dataset post too.

J
Richard Myers wrote:

Hi Josh,

I appreciate that you have recognised your "problem" and have the
energy and committment to undertake further training to attempt to
resolve it... but are you serious?

Flag the books.... just go buy the skillset you need. Sack/demote
your "lead developer" if you have too in order to afford an SA.
He/she is just an imposter if they are prepared to lead a team with
no solid architecture.

"Coding like hell" will just get you nowhere faster.

You need to identify a suitable methodology such as UML, and work from
there, but that will obviously require your "team" to learn the
methodology as well.

If you've "grown" the team into this situation then congratulations
are in order... but do yourself a favour and get the right people
with the proper skills doing the right job, right now. Dont diddle
about with books as a cheap substitute for a flesh and blood
professional.

Software projects are like children, they require different people
with different skillsets at different stages of their lives,
otherwise they tend to grow up with all kinds of weird and wonderful
disorders that make it really hard for them to play well with others
and make their own ways in the world.

If all this sounds a bit harsh then dismiss it, after all its your
future not mine..... and the smart arse within me is saying "Thank
God"!

;)

hth
Richard

[Richard Myers]

Yeah well fair enough.

Sometimes i do get a little fired up. Somone once said to me to lay off the
caffine. Perhaps they were right but i can type soooo much faster after a
couple of cans of Redbull. Please tell when i'm full of sh*t. I like to
learn too.

;)

The Visio has some impressive UML support built in, i remember watching a
dotNet show webcast on it.
It all seemed very worthwhile, a high level of integration between
VS/Visio/DAL/ and very accessible to the developer. The advantage here would
be you could "wizard" your team thru much of the initial learning curve and
gradually bring everyone up to speed.

If you do nothing else, you can move everyone from their own little note
taking stash, to a centralized model, that serves as an objective point of
reference. I realise there is always a gap between the theoretical text book
"holier than thou" model, and a practical working, not to mention fiscal
reality but i reckon it's false economy to skip the foundational steps of a
software development project.

If it's a really small team say 5 or less and you're all competent
communicators then i'm sure you can get away with it, but if your products
are great now, think of the opportunity cost in that they could have been
outstanding with an architect on board/consulting.

I stand by my original suggestion in that someone has to take responsibility
for this very important phase of development. If you cant take a week
off.... then someone should... bank a week tomorrow and save yourself a
month later.

I assumed you were talking about architectural documentation? Are you
building applications/class libraries/components/?

Richard

[Ray Cassick \(Home\)]

The problem here as I see it is kind of a catch-22 situation. At least you
have recognized that you have a problem and that is the first step.

The real problem is that, while there are many design paradigms available
that you can adopt, no one here can tell you which ones are the best, or
which one fits your situation better than you can. Unfortunately this takes
some time to research for yourself. Simply adopting A development process
for the sake of adopting ONE is not really a good thing IMHO.

This entire subject is something that many people can get very 'religious'
sounding about simply because there are so many people with opinions. Myself
included.

I started a very small software company (3 developers) that struggled with
this same issue. I simply don't have the cash, nor the time to invest in
supporting something like RUP (Rational Unified Process) simply because I
don't have the money to invest in the tools it takes. I would love an
end-to-end solution to be dropped right into my lap, but quite frankly I
understand that if one was dropped at my feet it would probably not fit 'my
needs' as a developer. It would be something cookie-cutter that some one was
pushing as the next best 'thing'.

If it helps at all, here is what I did (am doing):

0) MAKE the time to set up your processes. You might think that you have
to take time away from coding to do this but you don't. Of course you CAN,
but you don't have to. It all depends on how important this is to you. If
you can't commit to taking time away from doing your projects then simply
say that you will add to your work load by adding additional time to your
day after coding to tackle the project. Hard times call for hard work and
hard decisions. This is something my wife learned long ago when I started my
personal venture.

1) Decide that you NEED a process. But also understand fully how you
would benefit from it and also what you WANT from it. Unless you see the
benefit down the line you will eventually start to not follow it and then
the entire exercise is a waste of time. Write down a set of goals that you
want to achieve and then build your own process around those goals.

2) READ about what is out there. Since you are not alone don't think that
you have to do this alone. Delegate the research to your other workers to
study fro one week, each on a different paradigm that is available (how it
works, the tools used in it, the processes, etc..) and present this to the
rest of the group. If nothing else you will be better able to see what is
already out there, what you like and don't like about each paradigm and if
you can take this from here and that from there and evolve your own.

Here are a few that I researched:

RUP
http://www-306.ibm.com/software/awdt...res/index.html

SCRUM
http://www.controlchaos.com/scrumwp.htm

XP
http://www.extremeprogramming.org/

There are many more, I could not possibly list them all here. There is a
sizable amount of overlap among them and some very definite differences as
well.

3) MAKE the first move. Start small, don't bite off more than you can
chew on. Just like the old adage "how do you eat an elephant" the answer is
one bite at a time my friend. What I did was pick one pet peeve that was
always making me nuts, code conventions. Variable naming, stuff like that
always ends up being just a bit different between developers. DOCUMENT it
down to the smallest detail. Get everyone together and agree on what will be
the company 'Best Practice' for code conventions. Then, here is the really
hard part.. FOLLOW it. Start holding code reviews and make people follow the
spec that was agreed on. Trust me when I say that starting here begins to
snowball. Once you start to realize that having this documented frees you
from having to worry about it in the back of your head a light bulb will go
on and you will start to document other things.

4) Develop a standard document format. I have seen companies argue over
the dumbest things and this has been one of them. If you have to put your
foot down as a leader and simply say 'this is the format that I have decide
we will use for all our standards documents' then so be it. But also
understand that you have to be open to change. You are not all knowing so if
someone has an idea that is good, adopt it and move on.

5) Just like using version control for code (you do use version control
for code right?) you should version control your documented processes. They
will evolve and it is always good to track that evolution incase suddenly
you see something not work and you need to go back a bit and make changes.

6) Document everything. Process documentation for a software company does
not just mean documenting software procedures. You have to effectively
communicate between yourselves and also effectively document that
communication. Start keeping meeting minutes, tracking how attends, when it
was, how long it was, what actions who took out of each meeting. This keeps
your mind looking towards process management as a whole and not just
software process management.

..
..
..
..

Boy I went off on a rant here didn't I.... Well it is as I said.. a
sometimes religious type discussion.

I hope that I have helped a bit.

If you are looking to get some ideas about the actual TYPES of documents
used I might be willing to share some of the formats and stuff off line with
you.


"Josh Golden" <jo***@wachovia.com> wrote in message
news:40***********************@news.twtelecom.net. ..

i lead a small development team (based on some of my posts that might cause some people to choke themselves, but have no fear, i am NOT the lead
developer, the people on my team are great - i'm just the manager) for my
company. although we attempt to use good practices for development, we have no real experience in documentation of a project _before_ it's coded.

Are there any great books out there on how to document a project before we
code. For example, i actually hear that some people write classes off of a master document that lists all properties, methods, events, etc. We
basically just survive on notes, meetings, and the "code like hell"
methodology - which will kill us in the long run.

I have some great books on management, like the mythical man-month and
others, but I am interested in a book on documenting a software project
before the coding starts.

Thanks