[Nightfish]

I'm sure everyone has their stories to share about software development projects. Many people on the boards are still young so they are either learning the theory right now or are not that long out of university that they have forgotten it all. And of course we all know that in real life things don't quite look like they did in the text book. But this is ridiculous.

The companyI work at now - probably one of the largest in germany - has a pretty huge project going. Reasonable estimate of 2-3 years at least. I'm still somewhat new so I am still trying to be rather low key and not to butt heads with people that have been here for 10+ years. Yesterday I did come out and ask where our project plan and requirements document was. Imagine my surprise when I learned that we don't have one. So I asked if they wanted me to write one. Cue further surprise at the answer I got:

"What? Are you serious? We can't spend that much time just on paper. We need to have a working version out by the end of the year. Shut up and code".

... Code what? Nobody has any idea what we're even doing and who's doing what. There is exactly one guy that knows what needs doing and even he is losing track of it because, surprise, surprise, it's a lot of stuff.

I feel like I'm working for the Underpants Gnomes:
Step 1: Start Coding
Step 2: ???
Step 3: Working Program

What really cracked me up is when the head honcho came by and asked how many more people we need to hire to get this done by the end of the year. Cool. So we don't have money to spend on getting a decent roadmap and requirements document done over a month or two, but we can hire two more people to sit on their hands and have no idea what needs to be done? What are they thinking? Even if we get more people, how will they know where to start? There is nothing in the way of documentation. They need to wait until the one person who is basically our living project plan has time to fill them in. And guess what, he does not have time for that. He's working on day-to-day affairs, was sick for a week just now so there's some backlog there and then he'll be on vacation. Whoohoo.

The only thing that exists in way of documentation is a rough draft of the database and that is already over 50 tables large and estimated to be 1/4th to completion. And they expect to just wing this shit without a project plan.

I can already see this project going down like a boss and all I can think of is "thank god I already arranged to work on this for one year at most". So I'll have bailed long before the shit truly hits the fan.


From my experience, time spent planning is time well spent. Even when I was part of a two man project, we did not regret having a detailed project plan with milestones and everything broken down to individual tasks. We could have added another person to our team at any time and have them be productive within a day, tops. Likewise, if we both died, someone else could take over the project without much of a hitch.

This post has been edited by Nightfish: 14 July 2011 - 05:16 AM

[raziel_]

when?
Never mind this post.

This post has been edited by NoBrain: 14 July 2011 - 05:17 AM

[iniaes]

I'm still learning the basics, and even I know better than to just throw code at it tuntil it goes away. heck I have a sort of design document for my skill consolidation project.

I guess this is what happens when beaurocrats run everything, the professionals are marginalised whilst they all sip brandy and blab about how important they are.

[ishkabible]

i have to say i don't envy your situation. that sounds more than a little f'ed.

[creativecoding]

Sounds retarded. I'm surprised that the developers for a rather large company would operate like that.


But hell, I tend to do it too. The database design is actually one of my first creations. But that's mainly cause all of the stuff I do focuses around just database stuff. It helps me know what I'm doing and how I'm going to do it.

currently me and a friend are working on a huge project (it's mainly just me now). I'm on my third retry now because I _never_ wrote anything down, and eventually I get stuck with some inoperable, procedural-style, piece of crap.

That being said, can someone explain how to create these types of documents? Are there any examples lying around?

[Nightfish]

creativecoding, on 14 July 2011 - 10:10 PM, said:

Sounds retarded. I'm surprised that the developers for a rather large company would operate like that.

That's what happens when the people in charge only have a vague idea of how software is created.

creativecoding, on 14 July 2011 - 10:10 PM, said:

That being said, can someone explain how to create these types of documents? Are there any examples lying around?

There's definetly a lot of material around for this, as there is for anything. Personally I go by common sense and that works pretty well. It helps if you have a natural tendency towards order, I guess.

What you actually need to do depends a lot on the scale of the project and who's working on it. If it's basically just you, you can probably get away with a lot less than if you are in a team of 20 people with some fluctuation thrown in for good measure. Also whether or not you have to get your plan approved by someone.

I find it a good thing to start with the most general things and then break them down bit by bit. First step is brainstorming / querying the customer. What is my application supposed to accomplish? What's my target audience? What's my front end supposed to look like? etc Also everything else that migh be relevant to the project in any way. Start as broad as possible. You can always narrow it down later on. Starting with something specific like the database as Step 1 does not seem like a very good idea to me as it excludes so much. Certainly, the database is a key thing and I love working with databases but it's not the first step, imho.

Then try to give that some sort of structure. Like, one section for GUI things, then break it down by categories, administrator screens, user screens, etc. Then break those down to individiual screens. I like doing a mock up design of things as well because it gives you something graphical to show to people. Never show text if you can show an image.

All the while I'm crossing out things on my brainstorming paper / cards that I have carried over to the requirements document. And I'll add new things to the brainstorming pile as I think of them. Eventually the brainstorming pile is empty and I'll have a first draft for my project specs.

I like to aim for a document that you could give to anyone with no prior knowledge of the project and he could work on it after reading said document.

[salindor]

You know, I don't envy your situation. I mean you can do that sort of thing on a small scale; but doing it on a large scale really sux.

I am going to go on a limb and suggest that it exists, but unlike the things you been taught it is only in someones head and your going to have to spend time extracting it.

[jon.kiparsky]

This is, unfortunately, not uncommon at all. I'm a technical writer - I could give you stories, but since I'm using my real name I'll just say this is not uncommon at all.

You can deal with this in any number of ways - as a coder, you'll have to evaluate the situation and make your own decisions, but some possibilities might include
- do it anyway: just start writing down everything you know about what the code is supposed to do, and how it's being done. Put the documents in some visible place, possibly setting up a local wiki or whatever. If anyone asks, just say you're doing it so you can keep track of what's going on. Eventually, one of two things will happen: you'll be the one with the information, making you more valuable, or your colleagues will join in the effort, making the data more valuable.

- keep your head down and write code like you're told. Advantages: you don't get seen as a troublemaker. Disadvantages: when the project fails, you've got a failed project on your resume. If somehow it ends up going out the door, you might end up having to maintain it, which is worse.

- revise your resume and start passing it around

[darek9576]

Have you ever heard of agile methods? People dont like not being productive ( = writing documentation). They prefer to dive in give the prototype to the customer and get the feedback what needs changing. Moreover, its then easier for the customer to evaluate the requirements since without anything to see, its hard for them to find the words describing what they actually want or they assume things to get done without saying! Get the proptype done quickly - throw it away or base your solution on it by keeping it. Implement other features, give it to the cutomer.

One drawback is that customer needs to be heavily involved in developing the productand often they dont have time. Although, i bevlieve that incremental delivery is the approach to avoid a lot of paper work, i must admit that your company is crazy to go into a large project without some sort of requirements/design. People need to be aware of whats going on - what needs doing/changing etc.

Good luck anyway.

[jon.kiparsky]

Quote

People dont like not being productive ( = writing documentation

And that's exactly the confusion that's exhibited in the original problem. If "productive" simply meant "producing stuff" then cancer would be a healthy (ie, productive) development.

[darek9576]

Software developers are paid to write software not novels.

[creativecoding]

darek9576, on 16 July 2011 - 05:17 PM, said:

Software developers are paid to write software not novels.

Writing a piece of software like that is like writing a review for a book that never existed.

[jon.kiparsky]

darek9576, on 16 July 2011 - 06:17 PM, said:

Software developers are paid to write software not novels.

Really? Then you're not doing agile development, if you've never developed use case scenarios...

Software is a dynamic artifact. It doesn't just sit there like a bridge letting traffic roll over it (yes, I know this is a simplification...), it has to be modified constantly throughout its working life. Software which cannot be modified due to fear of breakage is already broken. Good documentation is not a "novel" it is part of the software. Like good coding style, it's not something that's immediately needed to make the code compile and run, but its value is obvious later on. Unfortunately, since the people who wrote the software are typically gone by the time the lack of documentation and good style start to show up as problems, mediocre programmers will always be able to get away with disparaging both.

Read the original post: here's a case where the management is enforcing a no-documentation policy. Is it making the team more productive? Would agile, without a purpose or plan, be any more productive? I don't think it would: agile has a different method for extracting and expressing requirements, but much of the agile methodology is specifically and consciously geared towards doing both of those well.

This post has been edited by jon.kiparsky: 16 July 2011 - 05:44 PM

[darek9576]

Now you are suggesting that agile programming is "programming without a plan". Thats a lot of crap. The whole point of agile is to spend more time on code so that its a better quality code, therefore easier to maintain.

If i develop a quick version of the software without too much functionality, its not only good for the customer but for me as well. I can see from what i developed any design issues - a design patter may emerge? - or any problems with implementation that customer needs to know about.

If i spend 2 weeks planning, designing, talking instead of writing, these issues would never see the light. That would mean 2 weeks wasted.

Agile is what most companies are now using and only the software that does not change can be developed,lets say, using waterfall model. However, one sure thing abt software as you mentioned is that it is bound to change.

Agile all the way. No novels.

[jon.kiparsky]

Quote

Now you are suggesting that agile programming is "programming without a plan".

Actually, I'm suggesting that you don't exactly understand agile, if you think it doesn't involve documentation, and you don't understand documentation if you think it's about "writing novels".
If you impose agile-ish methodology, as you seem to be suggesting, on a project in chaos, you will wind up with agile chaos. If you regroup and actually implement the agile methodology, you will produce documentation. It won't be in the form of a binder labelled "Requirements Specification" and another labelled "Technical Specificiation", but there will be plenty of material to tell the next programmers who join the team after you leave what it is that you did and why.
But they won't have that if you do the "agile lite" approach that you're describing. Not that you'll ever care, at least not until you have to work on a codebase produced by programmers like you.

This post has been edited by jon.kiparsky: 17 July 2011 - 10:19 AM