henrikjernevad, 24 days ago

@clobrano I find it helpful to think about what you want to achieve by writing the documentation. Who is it for? What do you want them to understand? Then think about what you need to say to do that.

Try to put yourself in the shoes of the reader. If they did not know anything except that which you have written, would it make sense? Have you introduced all terms before using them? Do you consistently use the same words for the same concepts? Is each paragraph conceptually coherent?

henrikjernevad, 24 days ago

@clobrano And of course, you get good at writing design docs like you get good at anything. You practice. 😊

clobrano, 20 days ago

@henrikjernevad thank you! I started thinking that this initial "pain" is more or less like the one after the first weeks of gym. It's part of the process, but I'd love to see examples of real cases

underlap, 20 days ago

@clobrano @henrikjernevad I gave some examples in my blog post. Unfortunately my design docs pre-2007 are confidential and I can't access them.

Generally, over the years my design docs have become shorter. I don't include detail which should be code or code comments as that will tend to go out of date quickly.

Capturing rationale and alternatives considered is like gold dust and a great gift to my future self. (It's really hard to remember that kind of stuff years later.)

clobrano, 17 days ago

@underlap @henrikjernevad I read your post, very useful thank you!
I get used to taking a huge amount of notes (like zettelkasten), but still struggling converting into something more accessible to share.

underlap, 17 days ago

@clobrano @henrikjernevad What headings do you include in a draft design doc? Here are some suggestions:

• Requirements
• Scope
• Out of scope
• Architecture
• Interfaces
• Major dependencies
• Operating systems supported
• Hardware platforms supported
• Configuration
• Security
• Performance
• Compatibility
• Interoperabiity
• Internationalisation
• Alternatives considered

clobrano, 16 days ago

@underlap @henrikjernevad
The first three are always in my documents.
Lately it is something like

• goals - what do you want to achieve
• reality - what is the current situation
• options - what can we do
• plan (research, devel, testing, release)

underlap, 16 days ago

@clobrano @henrikjernevad Interesting. That kind of design document is geared towards planning. The other main kind is geared towards describing the (intended) state of the system you are building. The second type gives you an opportunity to think through the options for how to structure the code before you get too invested in a particular piece of code.

clobrano, 15 days ago

@underlap @henrikjernevad yes, my current needs is to plan changes, so the idea is to have

• reasons
• snapshot
• how to move forward

underlap, 20 days ago

@clobrano @henrikjernevad Also, writing introductory material and defining terms early on has the advantage that my viewpoint is closer to that of a beginner. That doesn't last long!

underlap, 24 days ago

@clobrano That's a great question. Some suggestions:

1. Find and read good design docs.
2. Ask people to provide feedback on the design docs you write.
3. Search the web for checklists of topics to include.
4. Add your own topics relevant to the area you work in.
5. Work on your general writing skills, e.g. read "The Elements of Style" by Strunk and White.

1/2

underlap, 24 days ago

@clobrano
6. If you understand an aspect of the design clearly, write it up so others can understand it too. If you don't understand an aspect, write down a question about it and try to find the answer.

2/2