| ▲ | chanux 2 hours ago |
| > My jokes aren't funny and are actively confusing. I used to write technical documents in prose style, sometimes with meandering stories. I guess I picked it up from my early blogging days. I realized I hated reading some of them back. So I tried to keep it cut and dried. I do sometimes sprinkle a bit of colorful wording just to add a bit of humanity but only if it doesn't get in the way of the main message. |
|
| ▲ | bambax 6 minutes ago | parent | next [-] |
| > My jokes aren't funny and are actively confusing. Well, I found that sentence in the post was very funny ;-) |
|
| ▲ | clbrmbr 17 minutes ago | parent | prev | next [-] |
| isnt this what footnotes are for? |
|
| ▲ | shevy-java 2 hours ago | parent | prev [-] |
| Being short and concise is usually the better way. I tend to be too verbose in writing as I want to explain the context in more detail, but short, accurate, concise is best. Many developers fail at that too, though. Many projects do not have working examples. That annoys me the most. It sends a message of "I don't care about new users learning how to use my project". |
| |
| ▲ | andai 20 minutes ago | parent | next [-] | | >"I don't care about new users learning how to use my project" I published something the other day with minimal instructions, and felt briefly conflicted. But I figured, if you want to run it, you'll find a way! (It probably doesn't even work on other operating systems, but porting it would take what, 20 seconds of Codexing?) It was true before AI, and it's definitely true now. My intended audience is people who want to get their hands dirty. Though I suppose these days, that's the machine's job... | |
| ▲ | ibizaman an hour ago | parent | prev | next [-] | | Same for me. What helped is the realization that I was trying to cater to everyone in the same document. Now I try to follow the organization outlined in https://diataxis.fr/ I’m still very bad at documentation in general but I’m less dissatisfied when I come back a few months later. | | |
| ▲ | chanux an hour ago | parent [-] | | I had diataxis in mind when I wrote my comment. It's an important and excellent guideline on picking the style based on purpose of the doc. |
| |
| ▲ | ignoramous an hour ago | parent | prev [-] | | > Being short and concise is usually the better way. The golang docs are like this. As a novice, you are looking for detailed prose, but as you progress, you come to appreciate the terseness. |
|
