docs are hard, often harder than code

@_developit always*

@_developit that's why i don't do them

@_developit with code you at least know the problem you are solving, with docs - huge amount of opinions, different skill levels, never know whats clear, ambiguity all over the place .... docs is a nightmare

@_developit cc @adamd

@_developit Docs can sometimes be a good litmus test for API complexity/ergonomics too. If it feels like a feature needs way too much explanation and documentation...perhaps the API itself needs to be revisited.

@_developit For real

@_developit In some sense maybe docs are harder because code is read by ~1 engine, so you can optimize for that (and the feedback look is very quick), but docs are read by N people, how could one possibly optimize for all of them 🤔

@_developit I've never written documentation that didn't surface some bugs and/or result in me redesigning (and rewriting) parts of the APIs of the codebase.

@_developit I've been writing docs recently for an SDK and I always find it remarkable how much of a learning experience it is. It's a perspective to explain how to use something independent of its implementation.

@_developit I have so many feelings. The harder the problem, the harder to code, and the harder to document. Also, good docs and good code are hard to write. People can write bad docs and code without a lot of thought. It is also true that the best engineers I know write great docs.

@_developit @adamwathan This 👆🏻

@_developit True!

@_developit If the docs are hard, the code is bad. Nonetheless, try @DenigmaAI (not affiliated)

@_developit You mean getting motivated to write docs ;)

@_developit only for the first month or two, once you break them in they're great boots

@_developit @adamwathan Docs Driven Development 👌🏼

@_developit Definitely time consuming

@_developit I would say, more tedious

@_developit Docs are legacy the moment you touch the code again.

@_developit And a little boring

@_developit Any tips?

@_developit Truth.

@_developit APIs make sense to me as I write them, but if I have to write docs, they no longer make sense to me 😂

@_developit #จบนะ

@_developit What are your views on JS-Docs ? I find them pretty easy to write and read

@_developit Doubtful 😂

@_developit We’re using Documatic and adore it. Good times for sure, their team is doing amazing work.

@_developit Literally, I often spend more time writing proper docs than writing the actual code, I hate writing docs 😭

@_developit Agreed. As you dig deeper.

@_developit Agreed. That's why we created an open source static document generator for GraphQL: github.com/anvilco/specta…

@_developit The struggle is real

@_developit Writing code is the easiest step.

@_developit poorly documented code is hard. Documenting it yourself is even harder

@_developit With a big team, code can become harder and spaghettier without docs/specs 🫠

@_developit Then go read cheatsheets.