3 ms·
>What I wonder is: Why is this so personal? Looking at example given at this page, before the edit -- it looks like whoever wrote the library is being proud of
by Muromec 4y ago
>What I wonder is: Why is this so personal?
Looking at example given at this page, before the edit -- it looks like whoever wrote the library is being proud of this little trick they just invented. Look, look, mailer is just another kind of a view! Appreciate how neat it is that we don't invent another high-level concept but reuse existing stuff in a slightly different way. This is personal. Example on the right skips this part and focuses on how to use things.
Being proud of "this little trick we invented" is good ofc, but maybe it's place is in a conference talk or into video of something. Maybe whoever is reading the doc is not your mom and doesn't care right now.
It's a bit of a cultural shift from a community of cool people showing cool stuff to each other to more "it's just a job" kind of attitude. If you aren't there to appreciate clever tricks, it's just noise.
- imgabe 4y agoNah we don’t need to strip out every ounce of personality from something someone was kind enough to write and share for free. Anyone whose delicate sensibilities are so offended can just simply write whatever free library they’re using themselves.
- spondylosaurus 4y agoThis advice extends far beyond free libraries (and the linked article makes no indication that it's specific to that context). I've encounter all kinds of B2B SaaS docs full of worthless bloat, and I've written docs in the face of pressure from product teams who want to turn documentation into a Look How Cool We Are showcase. And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.