I find this pervasive idea that "documenting" things is just a thoughtless dump of facts very troublesome.
Certainly, most "documentation" I read is just a thoughtless dunp of arbitrary facts about some system, design, code, or event or what have you. But it should be better.
There are infinitely many true statements to make about some thing in order to document it. The art is in determining which ideas and facts about it are relevant for an audience, and finding a way to express those ideas and/or facts clearly for.that audience, in a logical order, using good prose, diagrams, etc. I think that's as hard as any other writing task, and arguably more valuable than many. Documentation captures facts for record and makes them accessible to some audience who otherwise would not have known about that thing. What could be a more important kind of knowledge work than that?
Certainly, most "documentation" I read is just a thoughtless dunp of arbitrary facts about some system, design, code, or event or what have you. But it should be better.
There are infinitely many true statements to make about some thing in order to document it. The art is in determining which ideas and facts about it are relevant for an audience, and finding a way to express those ideas and/or facts clearly for.that audience, in a logical order, using good prose, diagrams, etc. I think that's as hard as any other writing task, and arguably more valuable than many. Documentation captures facts for record and makes them accessible to some audience who otherwise would not have known about that thing. What could be a more important kind of knowledge work than that?