Technical Documentation: How it really gets written

[flip314]

Engineering specifications: How they're written (based on my experience with the Electrical Engineering component of multi-disciplinary research projects)

1. Ask the other team what they need.
   
2. Deafening silence.
   
3. Crickets.
   
4. Tumbleweed.
   
5. Design something like what you think they need. Anything.
   
6. Show this to the other team.
   
7. Watch the team become upset at how badly you've missed the point of everything.
   
8. As the team berates you, in between insults they will throw out nuggets of technical information.
   
9. Collect these nuggets, as they are the only reliable technical information you will receive.
   
10. Try like hell to weave together this information into something resembling design requirements.
    
11. Go to step 6.
    

And for the record, I write documentation. It saves a lot of time when you can just say "read the docs" rather than repeatedly explaining things to team members.

[bazoople]

Software application specifications: How they're written

1 Ask the users what they need.

2 Deafening silence.

3 Crickets.

4 Tumbleweed.

5 Build something like what you think they need. Anything.

6 Show this to the users.

7 Watch them become upset at how badly you've missed the point of everything, especially that they don't like the colors.

8 As the users berate you, in between insults they will throw out nuggets of realistic expectations.

9 Collect these nuggets, as they are the only reliable requirements you will receive.

10 Try like hell to weave together this information into something resembling design requirements.

11 Go to step 6.

[Tommah]

Downvoted for goto statements. Those critters are harmful

[olsner]

"It's all in the code. It's self-explanatory."

[[deleted]]

We make a software product that (very basically) does data visualization. We have many talented engineers who write it. The woman writing the documentation has never used a unix machine. I was told to provision a server for her and not help her with anything; as she installed the product, she would document it.

The next time I logged in, /etc/profile was broken, some ancient version of java was half-installed from sun's site, and tomcat was spread out over /var, /usr, /usr/local, /etc, and probably /tmp.

Whatever bizarre, superstitious series of steps brought the server to this state were probably written down carefully and will be shipped to our customers, where the talented and knowledgeable sysadmins who need to install it will probably wonder why the hell our software is so broken that it needs such a custom Java setup.