Fork me on GitHub
#off-topic
<
2019-12-09
>
seancorfield01:12:31

How many people find writing documentation to be exhausting? I've written about 3,500 words over the last couple of days (for expectations/clojure-test) and it just feels like an uphill battle... Any hints/tips for making it easier?

anonimitoraf01:12:13

haha, coincidentally, I'm also currently writing docs at work. I personally find it just boring and tedious, although, the biggest motivator for me is the fact that if the systems I design/write are not documented (clearly), chances are, when I leave the company, the systems will have to be either reverse engineered or thrown out. I think it would suck a bit to have a system you worked hard for, to just be thrown out.

seancorfield01:12:49

At one of my first jobs (mostly writing IBM 8100 assembler at an insurance company) I had to write a bunch of documentation for a project I'd created... and I learned later that they thought my docs were so bad that they hired a technical writer to completely redo them after I left!

anonimitoraf02:12:49

Hey, at least they kept the your code!

seancorfield03:12:43

True. It was a full-screen TTY-based editor. For drafting insurance letters using templates. All in assembler. Probably the first application I was really proud of!

anonimitoraf03:12:40

whats an insurance letter?

seancorfield04:12:48

I worked for an insurance company, in their car insurance division, so we were always sending letters to policyholders about their insurance. They wanted a full-screen editor -- a sort of mini-word-processor -- that could easily bring in standard paragraphs of text to form letters to customers, that they could then edit/customize before printing. It was the very early 80's so it was common to write that sort of stuff in assembler.

seancorfield05:12:10

The templates had placeholder text in that was automatically replaced by details from the policyholder's database record. It was a fun project. Long before "the web" 🙂

slipset06:12:20

FWIW Sean, I really enjoyed the docs you wrote for next.jdbc (or jdbc.next ;). Also the stuff you’re writing on expectations make sense if you want to see adoption.

seancorfield06:12:07

Thanks, @U04V5VAUN -- having http://cljdoc.org available (for next.jdbc) is really what's inspired me to work on docs for Expectations now. And, yes, I do want adoption -- so it's about time I started to push Expectations more. Especially if clojure.test gets spun out of Clojure 1.11 as a standalone Contrib library and I take over as maintainer of that, because I can use Expectations as a proving ground for improvements to core clojure.test functionality.

gklijs07:12:47

I find the most difficult part is maintaining the documentation to keep it in sync with the code. We currently have a process where we first do the documentation of a new service, before starting to work on it. With a library it's different cause you need more documentation on how to use it. But my only library so far only had a couple of functions.

leonoel07:12:38

I usually follow this framework https://www.divio.com/blog/documentation/

🔖 4
👍 4
4
Gulli10:12:02

Just let GPT-2 write the documentation for you while you have a coffee

💯 4
lread12:12:59

Writing good docs is hard for me and I continue to learn. I go through many edits. Working from a position of empathy helps to motivate me and reminds me the work I am doing is important, at least in its own little way.

Filipe Silva13:12:44

regarding code examples in docs, I find what really helps is to have those examples be references to real applications

Filipe Silva13:12:34

so instead of the docs saying "here's some plaintext that should work" it says "here is a reference to some source code region that I am testing"

Filipe Silva13:12:03

this requires tooling to extract regions of source code

Filipe Silva13:12:24

but then when your examples break, you know your docs might break too

Filipe Silva13:12:34

and it's kept in sync

Filipe Silva13:12:18

outside of code examples I think @UE21H2HHD’s "position of empathy" approach is helpful... but I find it exhausting to always try to keep up that mental model of a hypothetical novice and how they'd react to the current docs draft

Filipe Silva13:12:24

thinking of https://elm-lang.org/news/the-syntax-cliff makes it easier for me to keep it in perspective

Filipe Silva13:12:43

a lot of users really will not get beyond the "documentation cliff"

Jcaw13:12:59

Use voice recognition for the natural language parts.

jumar06:12:01

@U053XQP4S that's a very useful resource, thanks! Any ideas on how that relates to code comments and how to deal with challenge of outdated docs?

leonoel08:12:21

that looks like an orthogonal concern to me

leonoel09:12:18

the challenge of outdated docs is mostly a social one, like technical debt, the hardest part is to explain to your pointy-haired boss that it's time worth investing

Jcaw10:12:22

If it's a huge problem, you can try and bind your documentation to functionality, so docs have to change with functionality.

Jcaw10:12:17

Doctests, or outright deferring to tests for example usage & expected behaviour. IMO well-written tests are better documentation than documentation a lot of the time.

jumar10:12:14

@U053XQP4S Hmm, interesting. I still not sure how to relate this to code comments. Using the terminology of the "framework" I tend to write "explanations", especially in top-level ns docstrings as well as reference docs and perhaps sometimes even the other types of docs. I'm wondering if that can make it harder to produce/consume.

jumar10:12:34

@UPSUXBK17 Tests usually don't tell you why

Jcaw10:12:50

Mmm, of course. Only helps with direct functionality.

leonoel10:12:07

@U06BE1L6T As I understand the terminology of the framework, docstrings should be used exclusively for reference documentation (which may include basic examples).

4
lread16:12:09

with respect to keeping docs and examples tested and in sync, @U07FP7QJ0 has done some interesting work on this for kaocha. He has some of his docs generated from his tests. For example, https://github.com/lambdaisland/kaocha/blob/master/test/features/filtering/focusing.feature generates https://github.com/lambdaisland/kaocha/blob/master/doc/filtering/focusing.md

plexus17:12:49

Elixir also has something really cool in this space called "doctests". Basically you can embed little REPL session snippets in a docstring, and they will be run and checked like unit tests https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html

plexus17:12:31

If I ever apply for another grant for Kaocha this might be one of the features I would add

Filipe Silva17:12:27

what are these .feature files?

plexus17:12:31

They are Cucumber tests using a syntax called Gherkin

Filipe Silva17:12:45

it did look familiar

Filipe Silva17:12:11

kaocha looks pretty nice, I wonder if I can make it work in shadow-cljs

plexus17:12:03

I feel like we're hi-jacking Sean's topic here...

Filipe Silva17:12:21

yeah sorry 😄

lread17:12:26

is it ok to go off-topic under a topic in #off-topic? simple_smile

solf11:12:06

I have a very simple pre-push git hook to prevent pushing if there's DBTODO in my code, here it is:

exec 1>&2
ag DBTODO
return_code=$?
exit $return_code

solf11:12:34

it seems to work, but it doesn't write the output of ag DBTODO to the output, I can't figure out why

solf11:12:56

Nevermind, it doesn't actually work

borkdude12:12:48

it is just me or is this response not in line with the clojure etiquette? https://www.reddit.com/r/Clojure/comments/e7zbit/small_configuration_management_tool_for_clojure/fa92k3v/ > Keep it short, Stick to the facts, Use logic, Avoid rhetorical devices, Superfluous or opinion-laden adjectives (cc @yogthos)

Alex Miller (Clojure team)13:12:43

Flag it and message the mods (I am not a mod there)

Conor13:12:44

I assume it's one of those lost in translation things, because 'daddy' is a pretty weird name for a config management tool

😃 4
sogaiu13:12:49

naming is hard

👍 4
Mno15:12:37

It reminds me of the implied wording example where "Daddy I've been bad" and "Father I have sinned" mean roughly the same thing but have very different connotations.

andy.fingerhut17:12:29

What is the implied wording example you mean? I didn't see anything in the README that reminded me of either of those phrases, but could have missed it.

Mno08:12:50

Oh no the README is totally innocent. I meant the example I was about to state ("Daddy I've been bad" and "Father I have sinned" mean roughly the same thing but have very different connotations), which I had seen somewhere else before. But I've been told this is a bit on the edge of the Code of Conduct, so I'll veer off the topic for a long while 🙂

borkdude16:12:09

At least now you will remember its name 😉

henrik16:12:43

Maybe this will prompt a new trend of slightly (yet somewhat inexplicably) uncomfortable library names.

Lennart Buit21:12:39

such as Git 😛?

lilactown16:12:50

yeah the name is a big “yikes” from me

andy.fingerhut17:12:07

The first line of the README is "My father is a greate chef :)". Sounds like a library name from a person who they admire.

borkdude17:12:35

you mean this one right? https://www.chef.io/

andy.fingerhut17:12:33

The README I was referring to was for the library named 'daddy' that some people find cringe-worthy, which seems more likely to be based upon their mental associations of the word, rather than anything the library author intended.

sogaiu17:12:33

i think @conor.p.farrell got it -- "lost in translation" -- the author of the tool is from a country where many english words are imported and it's not unusual for the connotations to end up different or not entirely maintained

👍 4
lilactown17:12:23

I agree that the author clearly didn’t intend it, but it’s still a yikes

sogaiu17:12:41

may be there are better ways to communicate the info 🙂

sogaiu17:12:54

reference here to the comment on reddit

andy.fingerhut17:12:18

The comment now deleted from reddit, that is

lilactown17:12:24

I didn’t see the comment on reddit. I’m glad it was removed if it was rude or inflammatory

sogaiu17:12:56

although it had a point, there was extra info that seemed unnecessary

andy.fingerhut17:12:08

I don't recall it being any more rude than saying that the library name is a yikes -- I think borkdude thought it was irrelevant to the content of the library

sogaiu17:12:18

i think it mentioned being "repulsed" and would not consider using such a thing because of the name

henrik17:12:54

The person said that they find libraries named after food icky in one way or another. I get it, it sounds like a flavor of synaesthesia to me. I don’t know why it would be it would evoke negative feelings when used as a library name, and not for the actual food itself. Though I’m sure it’s not a logical thing.

sogaiu17:12:34

hard to understand others -- but even ourselves sometimes 🙂

sogaiu17:12:28

but possibly with a bit more emotion 🙂

andy.fingerhut17:12:31

Is there some popular usage of the word "daddy" that I have perhaps missed in the last 10 years or so?

sogaiu17:12:48

i am a bit curious too

lilactown17:12:50

there’s a heavy sexual connotation in english internet culture with the word “daddy” used out of context

sogaiu17:12:02

i guess i missed that 🙂

andy.fingerhut17:12:17

Sounds like a sub-culture usage thingy. It wasn't the first perfectly innocent word to be so tarnished, and certainly not the last.

sogaiu17:12:43

even not knowing that connotation i did find the name slightly weird

sogaiu17:12:05

for reference, i grew up with both english and what i presume to be the tool author's native language

lilactown17:12:10

it’s a reference to a specific kink. I would definitely consider reference to and jokes about it a part of the modern American culture, but maybe that’s just the twitter bubble I live in. It’s pretty much a meme at this point

sogaiu17:12:44

he he -- feel like rumpelstiltskin 🙂

andy.fingerhut17:12:37

Such adding of connotations to names has been orchestrated by popular figures before, too (I do not suspect that happened to the word 'daddy'): https://en.wikipedia.org/wiki/Campaign_for_the_neologism_%22santorum%22

sogaiu17:12:29

reminds me of the addition of a positive connotation to the word "geek"

andy.fingerhut17:12:45

Eh, sorry, probably not a good thing to link to too early on a Monday morning. Sorry. Need more coffee.

Mno17:12:23

Haha off-topic is a great place

Cameron17:12:00

Well I know what I'm naming my next library

andy.fingerhut17:12:20

geek, I hope 🙂

borkdude17:12:43

I was thinking: gag, a new linter that insults.

💯 4
👍 4
p-himik17:12:34

Linter result: "You made me gag with your (not (empty? s))."

lilactown17:12:07

connotations to words change over time, and we should try and be sensitive to the current meaning when choosing the names of our public projects

lilactown17:12:36

I don’t think the author of “daddy” is a bad person for choosing it, or should receive any ill will at all. I do think they should probably change the name if they want people to use it 🙂

Mno17:12:58

But yeah I guess the odd connotations not being known in other places is a fairly common thing. Even the same word meaning completely different things is surprisingly common. One of my favorite examples comes from Australia..

andy.fingerhut17:12:32

It seems appropriate to privately point out to the library author the current connotation of that name, and suggest they might want to change it.

☝️ 4
sogaiu18:12:38

i didn't suggest a change, but mentioned this discussion and passed on a link from english stackexchange

uochan19:12:09

@U0CMVHBL2 @UG1C3AD5Z Thanks for your pointing! I didn't know that. Is there a term that mean "father" that can be shorted to about 3 letters and more appropriate?

sogaiu20:12:20

may be it is good to ask outside this thread too. one idea is to look at a synonym site for some initial ideas and then ask for feedback. as an example of a synonym site, there is this: https://www.thesaurus.com/browse/father?s=t

Cameron20:12:55

We did it boys

Cameron20:12:38

I'm not sure about 3 letters, I wonder about something like "Papa" though?

uochan20:12:57

"papa" seems good to me

sogaiu20:12:41

like @UBCSS6NGK i also thought "papa" might work, but i don't trust my sense of what is appropriate (i didn't know about the situation with "daddy"). which is the main reason i suggest asking outside this thread :)

borkdude20:12:34

@liquidz.uo why not just "dad"?

borkdude20:12:44

the binary already has that name

Cameron20:12:32

I originally wrote something like that as well sogaiu, I keep trying to say it to figure out if it sounds weird and I can't tell ahahah

👍 4
borkdude20:12:57

@U4YGF4NGM I am wrong in thinking that "dad" doesn't have this weird connotation?

👀 4
lilactown20:12:19

yeah that’s true

uochan20:12:15

if so, "dad" is the best for me

gordonk22:12:24

I've been in this slack for five minutes and the bubble some people live in is disheartening and I hope not indicative of the clojure community. Every father of young children in the english speaking world hears daddy 100 times a day without getting the vapours. If porn culture is driving your english comprehension you might need to broaden your horizons a bit.

borkdude22:12:42

That must have been a strange introduction to the Clojure slack. I promise it's not like this every day (at least not based on what I'm used to) 🙂.

Mno17:12:17

Embrace the weird! Have a good laugh with languages because by the time you get used to it they've changed again 😅

sogaiu17:12:26

on that note, always enjoy this guy's talks / writings: https://en.wikipedia.org/wiki/John_McWhorter

❤️ 4
Mno17:12:22

Seems like a chill dude

uochan21:12:14

Just to clarify: doesn't "dad" have a weird connotation?

andy.fingerhut21:12:50

I really have no idea, but judging by the definitions of "dad" and "daddy" in the Urban Dictionary, "daddy" is the one with the heavy connotations. Compare these: https://www.urbandictionary.com/define.php?term=Dad https://www.urbandictionary.com/define.php?term=Daddy

👍 4
Mno21:12:18

Dad has a family connotation, Father has a priest/formal connotation, Daddy has a childish connotation but also the sexual one. At least as far as I know. I'm an American English speaker and spend too much time on the internet.

seancorfield21:12:15

(perhaps a reminder that despite being "off-topic" this channel is still covered by the Clojurians Code of Conduct and this thread seems to be veering close to inappropriate...)

seancorfield22:12:27

(the Australian ice cream image was certainly in violation so that has been removed)

Mno08:12:28

oh, my bad. Will avoid that in the future.

borkdude22:12:41

@seancorfield Maybe you misunderstand, but I don't think so. We were sincerely discussing a cultural misunderstanding by someone who accidentally named his library after some word that in some cultures have a sexual connotation.

seancorfield22:12:45

I understand very clearly. Just cautioning that these sorts of discussions have a tendency to go off the rails if folks get a bit "excited" about the topic... And I would have mentioned it hours ago if I hadn't been busy working...

borkdude22:12:17

a'ight, we probably have said enough about this topic anyway

uochan22:12:33

Thanks all! I'll rename to "dad".

👍 20