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 jdbc.next ;). Also the stuff you’re writing on expectations make sense if you want to see adoption.

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.

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 https://www.divio.com/blog/documentation/

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

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.

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

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"

this requires tooling to extract regions of source code

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

and it's kept in sync

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

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

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, https://github.com/lambdaisland/kaocha/blob/master/test/features/filtering/focusing.feature generates https://github.com/lambdaisland/kaocha/blob/master/doc/filtering/focusing.md

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

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

what are these .feature files?

They are Cucumber tests using a syntax called Gherkin

it did look familiar

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

there's an issue I can follow https://github.com/lambdaisland/kaocha-cljs/issues/2

that would be awesome! https://github.com/lambdaisland/kaocha-cljs/issues/2

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

yeah sorry 😄

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

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

done

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 🙂

such as Git 😛?

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 🙂

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

🙂

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: https://www.thesaurus.com/browse/father?s=t

We did it boys

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

@UG1C3AD5Z thanks!

"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

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

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

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