4 ms·

Author here: If the LLM revolution helps us get more accessible and better docs, I, for one, welcome it. Edit: I guess some commenters misunderstood my message

Author here: If the LLM revolution helps us get more accessible and better docs, I, for one, welcome it. Edit: I guess some commenters misunderstood my message. I'm saying that by serving also the needs of LLMs we might get more resources to improve docs overall.

9rx 1y ago
> more accessible and better docs Easy now. You might be skilled in documentation, but most developers write docs like they write code. For the most part all you are only going to get the program written twice, once in natural language and once in a programming language. In which case, you could have simply read the code in the first place (or had an LLM explain the code in natural language, if you can't read code for some reason).
- StableAlkyne 1y ago
  > you are going to get the program written twice, once in natural language and once in a programming language. How is this a bad thing? Personally, I'm not superhuman and more readily understand natural language. If I have the choice between documentation explaining what a function does and reading the code, I'm going to just read the docs every time. Unless I have reason to think something is screwy or having an intricate understanding is critical to my job. If you get paid by the hour then go for it, but I don't have time to go line by line through library code.
  - 9rx 1y ago
    > How is this a bad thing? It is not good or bad. I don't understand your question. > If I have the choice between documentation explaining what a function does and reading the code, I'm going to just read the docs every time. The apparent "choice", given the context under which the discussion is taking place, is writing your program in natural language and have an LLM transcribe it to a programming language, or writing your program in a programming language and having an LLM transcribe it to natural language.
    - StableAlkyne 1y ago
      Ah, my apologies then. I misread the post as an argument against generated documentation.
- deleted 1y ago
  [deleted]
bgwalter 1y ago
It does not give us better docs. The claude.md files are a performative action for the employer. No one will write APUE level documentation because everything is rewritten constantly in those code bases anyway and no one either has the skills or is rewarded to write like that any more.
- theletterf 1y ago
  That's why I feel tech writers need step in and help.
jacobsenscott 1y ago
We've seen this story many times before. Remember UML and Rational Rose, waterfall, big up front design, low/no code services etc. In every case the premise is "pay a few 'big brains' to write the requirements in some 'higher level language' and tools/low skill and low pay engineers can automatically generate the code." It turns out, to describe a system in enough detail to implement the system, you need to use a programming language. For the system to be performant and secure you need well educated high skill engineers. LLMs aren't going to change that. Anyway, this is tacitly declaring LLM bankruptcy - the LLM can't understand what to do by reading the most precise specification, the code, so we're going to provide less specific instructions and it will do better?
- theletterf 1y ago
  Oh, I remember. I'm an OpenAPI fan, for example. This time it feels a bit different, though. It won't erase the requirement of having high skill engineers, nor the need to have tech writers create docs, but it might indeed help focus on docs under a different light: not as a post-factum, often neglected artifact, but as a design document. I'm talking of actual user docs here, not PRFAQs or specs.
  - eddythompson80 1y ago
    It always feels a bit different doesn't it. This time it's though. Maybe. No definitely. Will see. We're waiting for AGI anyway, right?
    - theletterf 1y ago
      One can only hope. :)
  - esafak 1y ago
    The difference is that LLMs are more capable than the average coder, and rapidly improving. If you give a seasoned developer a loose spec, (s)he'll deal with the ambiguity.
- jrvieira 1y ago

9rx 1y ago

> more accessible and better docs Easy now. You might be skilled in documentation, but most developers write docs like they write code. For the most part all you are only going to get the program written twice, once in natural language and once in a programming language. In which case, you could have simply read the code in the first place (or had an LLM explain the code in natural language, if you can't read code for some reason).

StableAlkyne 1y ago
> you are going to get the program written twice, once in natural language and once in a programming language. How is this a bad thing? Personally, I'm not superhuman and more readily understand natural language. If I have the choice between documentation explaining what a function does and reading the code, I'm going to just read the docs every time. Unless I have reason to think something is screwy or having an intricate understanding is critical to my job. If you get paid by the hour then go for it, but I don't have time to go line by line through library code.
- 9rx 1y ago
  > How is this a bad thing? It is not good or bad. I don't understand your question. > If I have the choice between documentation explaining what a function does and reading the code, I'm going to just read the docs every time. The apparent "choice", given the context under which the discussion is taking place, is writing your program in natural language and have an LLM transcribe it to a programming language, or writing your program in a programming language and having an LLM transcribe it to natural language.
  - StableAlkyne 1y ago
    Ah, my apologies then. I misread the post as an argument against generated documentation.
deleted 1y ago
[deleted]

bgwalter 1y ago

It does not give us better docs. The claude.md files are a performative action for the employer. No one will write APUE level documentation because everything is rewritten constantly in those code bases anyway and no one either has the skills or is rewarded to write like that any more.

theletterf 1y ago
That's why I feel tech writers need step in and help.

jacobsenscott 1y ago

We've seen this story many times before. Remember UML and Rational Rose, waterfall, big up front design, low/no code services etc. In every case the premise is "pay a few 'big brains' to write the requirements in some 'higher level language' and tools/low skill and low pay engineers can automatically generate the code." It turns out, to describe a system in enough detail to implement the system, you need to use a programming language. For the system to be performant and secure you need well educated high skill engineers. LLMs aren't going to change that. Anyway, this is tacitly declaring LLM bankruptcy - the LLM can't understand what to do by reading the most precise specification, the code, so we're going to provide less specific instructions and it will do better?

theletterf 1y ago
Oh, I remember. I'm an OpenAPI fan, for example. This time it feels a bit different, though. It won't erase the requirement of having high skill engineers, nor the need to have tech writers create docs, but it might indeed help focus on docs under a different light: not as a post-factum, often neglected artifact, but as a design document. I'm talking of actual user docs here, not PRFAQs or specs.
- eddythompson80 1y ago
  It always feels a bit different doesn't it. This time it's though. Maybe. No definitely. Will see. We're waiting for AGI anyway, right?
  - theletterf 1y ago
    One can only hope. :)
- esafak 1y ago
  The difference is that LLMs are more capable than the average coder, and rapidly improving. If you give a seasoned developer a loose spec, (s)he'll deal with the ambiguity.
jrvieira 1y ago