 Fallacies that engineers* believe about documentation: - Anyone will read more than a page of your documentation. * It's me, I'm engineers. 21 comments
@hrefna From your writings on hachyderm, I'd expect that you could have a good series of long form blog posts about any number of subjects. Would people read it? maybe not, but you're writing for your own benefit (2+3); you need to do (3) because 6 months from now you need to see your own chesterton fence. Personally, I can only write long form because I use far too many characters to express myself. @hrefna What I've learned over the years re writing: - My writing style is boring. - Assume no one will read beyond the 1st heading. - Keep the # of words in the landing page/README and esp the 1st heading very short. - If RE coding, place a copy-paste friendly example in the 1st heading. - If rant/doc, write an accurate & *short* TLDR in the 1st heading. - Do the rest of the docs as you normally would. Expect folks to read them *only* when trouble-shooting. @bahmanm I had a class in school—Engineering Practicum Introductory Course Sequence—where the professor had us format our final projects in a particular way with an executive summary in front. If he liked the executive summary enough to give you an A he wouldn't read the rest of what you wrote. These days it isn't uncommon for me to have an executive summary, a tl;dr, a technical summary, and a 1-page overview. >_> Not arguing w/ the principle but writing those abstract sections is so demanding/draining for me that it makes it impractical in my case 😅 @hrefna @aburka I plan to use the nivenly discourse to send a fairly strongly worded short post with my thoughts about haidra, and why I think the only step I could personally accept from nivenly is to remove haidra from the list of supported projects, and first focus on a proper process for members to give input and approve/veto projects, since I indeed think my membership is directly tied to the supported projects. @hrefna @aburka However I neither have the knowledge nor the experience to write up a more productive post about that ""proper process for members" part. I do have very strong feels for both opensource AI projects being a necessity, and these from the ground up, with their main mission, being to counteract the ethical issues of company-backed projects. And as hrefna wrote up quite eloquently, this is neither that, nor is there a serious attempt to engage at all. My conclusions here are basically: 1. What nivenly has as a stated goal is a member-driven co-op where individuals can and do drive change. In that model, it isn't what "nivenly does" it is what "we do," together. I'm of the view that this is admirable 2. HOWEVER they don't seem to know what they are doing in order to enable that and are hitting a lot of what I'd call "unforced errors" along the way 3. Some of those unforced errors are things I'd view as existential threats 4. The problem I am seeing is if there is sufficient dissonance between an individual's ability to drive change and the rhetoric, it is going to be a Problem™ and one I have very little patience for, and fixing that is more work than I am signing up for right now (it requires access to a member list and a lot of time). So it comes out to the same basic conclusion—this is a litmus test—but I think I've gotten there via a different route. I like the "show, dont tell" paradigm. That is, I'd rather give examples of code snippets that show how to use my tools, and give the briefest possible explanation of how it works. I also worry about the "documentation gets stale" aspect, so ive been tempted to have the documentation snippets integrated with a test suite so I'm confident they are correct if my build passes. But that might be overkill.  @hrefna at least if you have documentation you can get mad at the people who don't read it. I worked with student engineers at Purdue on projects (exhibits) for my local science center that could take years and thus saw several changes to who was on the team working on it. I cannot scream enough about the students who did NOT read their predecessors' documentation and then proceeded to make the exact same mistakes their predecessors made. AND as the customer how rarely they talked to ME. @hrefna right?! Also, did it not occur to you that maybe there was a reason they didn't do x? If you read here you'll see they did do x and they managed to set the building on fire (ok the fire is an exaggeration and didn't happen but I swear over five years of working with them I expected it to). That said, there were some really great projects with very solid teams too. Just the bad teams...smh @hrefna read the documentation and talk to the customer. I mean, this is (or should be) engineering 101. Or at Purdue I think it was engineering 131, which my wife taught so I KNOW they were taught. Lol.  IMO (Yes it’s a hot take, and honestly I should probably reconsider): If people don’t read the docs I prepared, it’s their problem if they don’t get something. |
Gregory's Server
I've written maybe 10-20k words in the last two weeks. I anticipate that people will read at most 250 of them.
Why so many when they'll read so few:
1. Annoyingly, they all will read different sets of 250 words.
2. A lot of it is "let me establish that I have thought this through and have a plan." They read 250 words and skim a few more pages to establish that, see that there are 27 more pages, and go "great, xe has this."
3. Because _I_ want to remember what the hell _I_ was thinking.