AI for writing documentation

hruodr · 2026-02-16T21:15:49+0000

JohnK said:
I write my notes, docs, etc in markdown first; this allows me to keep my notes in plain text and I can view them with my text editor with fancy syntax highlights.

My normal documentation are short, concise commentaries in the source. My programs are for personal use. Your approach is good for someone wanting to spend time documenting manually. But even the AI can be used to get a first draft.

zester · 2026-02-16T21:15:55+0000

wolffnx said:
ok...this is getting annoying , is there some how of block words in the forum? like AI???????

Well you could just not participate in a forum topic titled "AI for writing documentation"

wolffnx · 2026-02-16T21:46:50+0000

yes, the AI lover boy dont appear no more ..it works

"ignore" is the keyword

astyle · 2026-02-16T22:31:25+0000

When I was in college, we were taught to put in the effort to make good comments into code, so that it's readable by both machines and humans. Not writing proper documentation for your own code resulted in 50% deduction of the credit you got for a class assignment.

And now? it seems to be a forgotten skill. 'Vibe coding' is supposedly the 'in' thing, and computers can as well be black boxes that have minds of their own. Like a God or a pet.

[SARCASM]Real programmers don't write documentation. It's the dirty work that needs to be outsourced to the stupid unwashed masses, for as cheap as possible.[/SARCASM]

[SARCASM]Real programmers write the Great American Compiler from scratch, in a hurry, with no commentary, then try to use it to write everything else.[/SARCASM]

Espionage724 · 2026-02-16T23:09:06+0000

wolffnx said:
"ignore" is the keyword

Imo that shouldn't even be a feature on public forums; if you're on the forum you already agree to its contents, and it forum moderators find it fine why self-censor?

Afaik someone posting positively about AI one day doesn't necessarily define their character or who they are; they might talk about something completely different like source code for something on ports; would you benefit from not seeing potentially useful information because of past discussion? Maybe later they'll post something anti-AI, but it wouldn't be seen because of the previous AI-related ignore block.

Worst-case I imagine it affects conversation flow on threads if someone is willingly blocking posts from one user and selectively responding (when they could respond to the blocked poster and have others able to be included too; the block only serves privately on a public forum); I prefer organic anything-goes

bakul · 2026-02-16T23:21:26+0000

Espionage724 said:
Imo that shouldn't even be a feature on public forums; if you're on the forum you already agree to its contents, and it forum moderators find it fine why self-censor?

It is perfectly fine to ignore people for whatever reason! Better to ignore some people than try to force them to stop (because they're never going to) or to escalate things further. Even on Usenet we had "killfiles" to ignore (mainly) trolls.

Espionage724 said:
would you benefit from not seeing potentially useful information because of past discussion?

So it goes!

CShell · 2026-02-16T23:47:32+0000

LibreQuest said:
Can't you just use a text editor to write things?

LOL --- I used to write entire papers using nroff(1) and vi(1)

...

But then WYSIWYG came along and everyone switched to that.

nroff(1) is a dying art I guess...

CShell · 2026-02-16T23:51:37+0000

But.. in answer to your original question. man(1) pages were usually hand created using vi(1) and/or emacs(1) or similar back in the day. Of course we just copied (another) existing man(1) page and edited that file into a new man page for our needs.

This is how... the UNIX was won !

cracauer@ · 2026-02-16T23:52:05+0000

TeX or nuffin'.

CShell · 2026-02-16T23:58:39+0000

cracauer@ said:
TeX or nuffin'.

Edited: Yup - there is LaTeX too

.

atax1a · 2026-02-16T23:59:41+0000

still is!

wolffnx · 2026-02-17T00:21:09+0000

Espionage724 said:
Imo that shouldn't even be a feature on public forums; if you're on the forum you already agree to its contents, and it forum moderators find it fine why self-censor?

Afaik someone posting positively about AI one day doesn't necessarily define their character or who they are; they might talk about something completely different like source code for something on ports; would you benefit from not seeing potentially useful information because of past discussion? Maybe later they'll post something anti-AI, but it wouldn't be seen because of the previous AI-related ignore block.

Worst-case I imagine it affects conversation flow on threads if someone is willingly blocking posts from one user and selectively responding (when they could respond to the blocked poster and have others able to be included too; the block only serves privately on a public forum); I prefer organic anything-goes

agree about that, is not fine blocking or ignore someone only for a word and asume the class of people he are for that,
maybe is a good person
but..is AI lover, and they are a virus, today is a post,tomorrow another,and again..and again..and again
hey, I dont want to see it, AI toilets / AI for wiping their ass /AI OS..etc...etc..
is a big NO

astyle · 2026-02-17T00:44:04+0000

There are already AI toilets on the market, if you know what to look for... But their manuals are of pretty crappy quality, because they are NOT by well known makers like Kohler.

As for latex - gloves, anyone?

CShell · 2026-02-17T01:31:46+0000

zester said:
Microsoft AI CEO Mustafa Suleyman, and his exact words were “So white-collar work, where you’re sitting down at a computer, either being a lawyer or an accountant or a project manager or a marketing person — most of those tasks will be fully automated by an AI within the next 12 to 18 months.”

Let's break this down:

Microsoft, a company that is pretty much "betting the farm" money wise on AI
The "Microsoft AI CEO"
Says that [most of white-collar tasks] "will be fully automated by an AI within the next 12 to 18 months."

... and you expected the Microsoft AI CEO to say... "exactly what"?

JohnK · 2026-02-17T01:35:05+0000

hruodr said:
My normal documentation are short, concise commentaries in the source. My programs are for personal use. Your approach is good for someone wanting to spend time documenting manually. But even the AI can be used to get a first draft.

ugh! So intead of kindness (-e.g. "Looks like you spent a lot of time making that utility, John. Nice work. Although it doesnt seem to fit my imediate need but I'll be sure to pass along the word if I notice anyone needing something like that." to which I would have responded with sommething like: "Oh thank you for the kind word and thoughts. Yes, I did and I am very proud of my efforts.") you choose to dismiss my program without reading and/or trying to see the forest through the trees.

Actually, I wrote the utility for myself (-i.e. instead of taking notes about the mdoc macros I decided to keep my notes in C) but decided to release it publicy because I thought it might lower the technical bar a bit for people to offer help in writing/fixing documentation for others. For example people could help fix bugs in *BSD man pages or in utilities because writing markdown is a bit more widely known than `mdoc` macros but they may still be good at technical writing. ...along with 10's of other ideas like: "creating quick and simple PDFs, HTML, etc. documents" or "just converting personal notes to man pages" or ...

But again, `troff` is not what you want (you people keep saying 'troff' on a BSD forum for some weird reason); if your utility is for BSD, you want `mdoc`. I also offered constructive advice about how AI tends to write man pages (especially how it fails to conform to mdoc macros; 'BSD treats mdoc as semantic markup, not formatting').

But, thanks for not choosing kindness (not a lot of that going around here).

But as far as the point about AI and/or interns writing documentation:
Isn't technical writing a class a CS has to take?
Do you not write your specifications before you code (who writes code before they know what they want)?

zester · 2026-02-17T01:37:27+0000

CShell said:
Let's break this down:

Microsoft, a company that is pretty much "betting the farm" money wise on AI

The "Microsoft AI CEO"

Says that [most of white-collar tasks] "will be fully automated by an AI within the next 12 to 18 months."

... and you expected the Microsoft AI CEO to say... "exactly what"?

My point was directed at another commenter who is convinced that the us government is going to let Microsoft crash the us economy in the next 12 - 18 month by eliminating 60% of the workforce. Which is absolutely ridicules. I mean we price control milk and corn so the market remains stable.

JohnK · 2026-02-17T01:40:48+0000

zester said:
You’re the only one making this personal. I offered a clear challenge, but now you’re backing out. If you’re going to criticize code "human or AI" it’s fair to show your repositories.

I dunno. I think I'd have to go with atax1a on this one. (s)he offered their code for the AI to document, and that documentation would/could have been checked against something they already wrote, by us. Seems a more fair challenge to me.

zester · 2026-02-17T01:43:52+0000

JohnK said:
I dunno. I think I'd have to go with atax1a on this one. (s)he offered their code for the AI to document, and that documentation would/could have been checked against something they already wrote, by us. Seems a more fair challenge to me.

My point was atax1a is criticizing others work without showing us there's. They look like a hippocrat.

JohnK · 2026-02-17T01:48:10+0000

zester said:
My point was atax1a is criticizing others work without showing us there's. They look like a hippocrat.

Maybe (and I sorta figured that) but, atax1a did lay down the challenge first (which I think would be a fairer/cooler one) and was returned with an insult. ...I think that would have been a really good challenge. atax1a could be a really good technical writer; we'll never know.

astyle · 2026-02-17T02:58:54+0000

zester said:
My point was atax1a is criticizing others work without showing us there's. They look like a hippocrat.

Even ChatGPT's English language skills (like spelling and grammar) are better than that.

But asking ChatGPT or Claude AI to do a code review AND write documentation is asking a bit too much, I'd say.

I mean, have you heard of 'Perl Haikus' that all do the same thing, are all written in Perl, but look vastly different? Or trying to translate a complete program from say, Ruby into ASP.NET ? Or better yet, from brainfuck into C#.NET ? Good luck documenting even one line of brainfuck in a way that someone who never heard of brainfuck can understand.

And, do you realize that 'Hippocrat' is someone credited with creating the field of medical ethics? Ever heard of the Hippocratic Oath?

Oh, and criticizing others' work without showing theirs - that happens all the time. If you see enough examples of quality code, you'd know what makes for good, readable code that actually does the job correctly. But if you can confuse an AI to the point that it produces nonsense documentation after reading your code - maybe your code is the problem.

JohnK · 2026-02-17T03:24:50+0000

Awe crap?! Now astyle is gonna get ignored.