Fork me on GitHub

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?


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.


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!


Hey, at least they kept the your code!


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!


whats an insurance letter?


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.


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" 🙂


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


Thanks, @U04V5VAUN -- having 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.


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.


I usually follow this framework

🔖 4
👍 4

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

💯 4

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 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"


Use voice recognition for the natural language parts.


@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?


that looks like an orthogonal concern to me


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


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


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.


@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.


@UPSUXBK17 Tests usually don't tell you why


Mmm, of course. Only helps with direct functionality.


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


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, generates


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


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?


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


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

Filipe Silva17:12:21

yeah sorry 😄


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


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
exit $return_code


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


Nevermind, it doesn't actually work


it is just me or is this response not in line with the clojure etiquette? > 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)


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

😃 4

naming is hard

👍 4

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.


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.


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 🙂


At least now you will remember its name 😉


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

Lennart Buit21:12:39

such as Git 😛?


yeah the name is a big “yikes” from me


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


you mean this one right?


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.


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

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


may be there are better ways to communicate the info 🙂


reference here to the comment on reddit


The comment now deleted from reddit, that is


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


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


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


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


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.


hard to understand others -- but even ourselves sometimes 🙂


but possibly with a bit more emotion 🙂


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


i am a bit curious too


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


i guess i missed that 🙂


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


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


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


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


he he -- feel like rumpelstiltskin 🙂


Such adding of connotations to names has been orchestrated by popular figures before, too (I do not suspect that happened to the word 'daddy'):


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


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


Haha off-topic is a great place


Well I know what I'm naming my next library


geek, I hope 🙂


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

💯 4
👍 4

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


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


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 🙂


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..


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

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


@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?


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:


We did it boys


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


"papa" seems good to me


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 :)


@liquidz.uo why not just "dad"?


the binary already has that name


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

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

👀 4

yeah that’s true


if so, "dad" is the best for me


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.


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) 🙂.


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


on that note, always enjoy this guy's talks / writings:

❤️ 4

Seems like a chill dude


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


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:

👍 4

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.


(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...)


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


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


@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.


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...


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


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

👍 20