Learning to like design documents by Julia Evans.
From the post:
Hi everyone! Today we’re going to talk about software engineering and process!
A design document is where, before starting to implement a system, you write up a thing explaining what the system is supposed to do first and how you’re planning to accomplish that. I think there are basically two goals:
- tell people what you’re doing
- figure out design problems with the system before you’ve been coding for 2 months
I understand that it’s super important to think ahead a lot before huge projects, but a little bit of thinking can be helpful even for smaller projects. I asked some people recently if they write design docs for small projects and some of them said “yeah totally! small ones! it helps! :D”.
I used to get kind of grumpy when someone was like “hey julia can you write a design document for your system?” It would seem like a reasonable idea, though, so I’d try to do it! But the first couple of times I tried to write one I felt like it didn’t actually really help me! I liked the idea in principle, but I didn’t really know how to apply it and I felt like it was hard to get good feedback.
Last week I wrote a design doc and I thought it was sort of helpful. Here are some current thoughts.
…
Be forewarned that Julia is a gifted writer and you will enjoy her posts more than your design documents. 😉
Still, Julia makes a great case for the use of design documents (a/k/a “documentation”).
Unless your job security is tied up in undocumented, spaghetti COBOL code (or its equivalent in another language), try putting Julia’s advice into action.
If you are looking for really broad but practical reading in programming, check out Julia’s list of all her posts. Pick one at random every week. You won’t be disappointed.