3 ms·
I can only directly relate to solo/small-team projects: I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...)
by dgb23 6y ago
I can only directly relate to solo/small-team projects:
I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive.
I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly because we have a limited capability of keeping stuff in our heads at any given time.
A typical categorization of these documents would be:
- specification: describing the thing you build in detail
- todo-lists: organizing actions
- guides/instruction: describing usage of the thing you build in a accessible manner
- meeting & discussion protocols
The thing is: None of these things are extra or can be avoided. The only difference is whether you write them down or not.
The article describes something I would put into the fourth category, or maybe a fifth where you describe intent historically (like design documents).
I personally don't write design-documents or ADRs, nor have I ever seen them. But I assume that these become valuable in larger organizations and teams with a higher communication overhead. As soon you need to talk about these things over and over you want to write these down.
- rabidrat 6y ago> As soon you need to talk about these things over and over you want to write these down. This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.
- dgb23 6y agoI just started to write anything down basically... When a collaborator or client talks to me or when I think about something, then I open a markdown file (first often just a notes.md) and just write in bullet points, and gradually organize it into categories. I put these in version control as well since a while. Thought experiment: if something is not worth writing down, is it worth discussing?
- rmdashrfstar 6y agoYes, there are many things worth discussing which would be better left not written down.
- tsimionescu 6y ago> Thought experiment: if something is not worth writing down, is it worth discussing? Writing things down in a way that can be consumed by others is usually significantly more work than discussing that same thing live (whether in text or verbally). As such, I would say that the answer is obviously yes.
- pjmlp 6y agoNot really because there isn't a JIT budget in most projects, and they usually only get allocated via escalations, some of which imply doing the work for free.