Comment by steindavidb
5 years ago
> The most underrated skill to learn as an engineer is how to document. Fuck, someone please teach me how to write good documentation. Seriously, if there's any recommendations, I'd seriously pay for a course (like probably a lot of money, maybe 1k for a course if it guaranteed that I could write good docs.)
Highly recommend a journalism class at local community college.
Or just learn how to take notes. Notes should be made with the intent that someone new could understand what's going on. With that approach, if you can't make good notes, you're thinking too much about what you know and less about what others don't.
Can you elaborate on that? Why journalism in particular? Have you done this? Are you better at docs?
I studied journalism at college as part of a more general media studies course.
It does help but I am not sure I would describe _my_ education as a panacea.
The main reason it was good was because it helps frame how you think of writing,
The most important things go first. Statement of fact, then you go into what the implications are, then you start introducing less and less relevant elements.
when you’re writing you keep the 5 “W’s” in mind, make sure you answer them. (Who what where when why), for instructive documentation you add: How.
Obviously an education bakes this into you in a better way than I can convey here.
What I learned is probably only decent for writing overviews.
Personally I find structure to be the biggest bottleneck/difficulty when making documentation.
What do others normally struggle with that don’t have this education?
I recommend a class on instructions.
Learning how to write proper instructions is the gateway to proper documentation.