3 ms·
I love architecture docs, but find they're often written using a funny process: 1. Spend a long time writing the doc. 2. Wait for a person to chance upon i
by closed 6y ago
I love architecture docs, but find they're often written using a funny process:
1. Spend a long time writing the doc.
2. Wait for a person to chance upon it.
3. Hope you anticipated their questions.
It seems like the most important thing a person can do is reverse this:
1. Say who the doc is for.
2. Find that person. Ask them to try a lil contribution.
3. Frantically write / revise the doc.
IMO it's a lot like creating a presentation. The earlier the feedback the better!
- steveklabnik 6y agoI like this idea a lot, but you will cause a lot of people to bounce at step 2. Or at least, that has been my experience over the years. No matter how much you reassure them that it is okay if stuff is confusing and in fact you'd like to know about it so you can fix it, they'll say "great" and then go radio silent 99% of the time.
- ralmeida 6y agoSounds right to me too. One quicker way to improve the 'first process' is to change only step one - do not spend a long time, but instead write a few paragraphs with what's most important and/or top-of-mind. Often, this opens the door to more contributions and questions. Of course, update accordingly whenever you find yourself in a discussion about something with a contributor (no matter if the architecture doc is even part of the discussion or not).
- dognotdog 6y agoI feel like for any long-running project, that person is at least ME. If I haven't written down some architectural information for complex projects, when I revisit a project after it being dormant for half year, I need to poke around to figure things out again. If I have written down architecture notes in the first place, they are very helpful at this point; and if I haven't, it's a good time to start because I'll be acutely aware of the non-obvious parts as I re-familiarize myself with the code.
- closed 6y agoI usually reach for a friend, or someone I've met before, since using the first version of a doc is asking a lot! (And they're often part of the target audience).
- gjvr 6y agoYep, feedback is valuable. And the earlier the more valuable (it's like NPV...). I love coding so much, and find it really hard to express ideas in natural language, so that in the end documentation... doesn't happen as much as it should. What I find that really helps is the following: 1. Write down architecture specs (with interface specs etc), before coding. Not bloated, but really minimalistic. 2. Review these ideas with peers. 3. Happy coding and refine the docs.
- j1elo 6y agoA question can be seen as a bug reported against the documentation... Apart from answering them, I end up converting 15% - 20% of questions into some revised content of my docs.
- ryanSrich 6y agoMost documentation follows that first path. With a step 4. that is basically "only update this when something is broken, or when we're hiring someone new". Doing documentation well, especially if you're working on brand new tech, is very frustrating and difficult. You're often moving too fast to find the time to retroactively update documentation, and you're right back into the viscous cycle of it constantly being out of date. I don't know what the solution is.
- deleted 6y ago[deleted]
- rapnie 6y agoThis is also the idea behind Readme Driven Development. See https://news.ycombinator.com/item?id=25222601 https://news.ycombinator.com/item?id=25222601