5 ms·

People go to Stack Overflow because the docs and error messages are garbage

20 points by rrreese 3y ago

al_borland 3y ago
Sadly the docs are error messages are not seen as part of the product and something that is needed to make something complete. Shipping fast and constantly adding new features has pushed good documentation to the backseat. It’s something that’s nice to have, but almost no one prioritizes, so it never gets done. From what I’ve seen, it is also something that comes with a mature team, as some stability is needed before a team starts to talk about documentation and standards. The constant churn of teams hurts documentation and error messages a lot. Why bother documenting or writing good errors if you won’t be around in 2 years to deal with it? More people need to stick around long enough to feel the pain of their bad decisions and laziness.
- mangamadaiyan 3y ago
  > Shipping fast and constantly adding new features has pushed good documentation to the backseat I'd just like to add -- shipping fast and constantly adding new features has pushed _almost everything else_ -- including design, and product quality -- to the backseat. Design documents are a rarity these days, forget about well-written and well thought-through design documents.
floxy 3y ago
Is anyone trying to use LLMs to generate documentation?
karmakaze 3y ago
In my experience, the docs are fine and mostly better than a random SO answer. A reason many people use it is because they're lazy or want to get past their hurdle with a quick answer rather than understanding things beyond their current issue. Any time I run into one of these, I'll post a reference to the actual docs as a comment in the top/accepted answer.
- db48x 3y ago
  Agreed. So many of the people who ask questions on the Emacs stackexchange have never even looked at the manual. Emacs has excellent documentation, and often there will be a whole chapter dedicated to answering that specific question. The title of the chapter will have the same key words as their question. And the manual is readable right inside Emacs! But by asking the question on SE, they can get someone else to go to the trouble of doing a keyword search on the table of contents to find the relevant chapter, then paste in the first paragraph of that chapter. It's laziness, pure and simple.
  - egberts1 3y ago
    Excellent documentation? For Emacs? There is such a thing as overloaded and non-user-centric documentation that is rich in details (if you already knew a few Emacs-type keywords)
    - db48x 3y ago
      The Emacs documentation really is quite good. It is user–centric, as you say, starting by naming the things the user can see and interact with when they run Emacs (the menu bar, the tool bar, etc, etc) before going on to more complex topics, such as how commands are given via the keyboard or mouse. While it is detailed, it can hardly be called overloaded. The real reference material is in a completely different book, the Emacs Lisp Reference Manual. There is also a FAQ, and if you’ve never programmed in Lisp before then there is the Emacs Lisp Intro. Then there are something like 60 other manuals for various packages that come with Emacs, like Org Mode or the calculator. These all serve to keep the core manual from becoming overloaded with details. You can read them all online at <https://www.gnu.org/software/emacs/manual/ https://www.gnu.org/software/emacs/manual/>, should you care to try to prove me wrong. I estimate that about 30% of questions on the Emacs StackExchange can be answered by quoting from that core manual, another 20% by the FAQ, 20% by the Elisp Intro, the Reference, or the docstrings of individual commands, and another 10% by the manual for Org Mode. The calculator comes up occasionally too. Perhaps 10–20% of the questions on the site are actually interesting questions that require real thought or a look at the source code.
3seashells 3y ago
If you can search it in the docs, you already know the question well enough to answer. Stackoverflow has answers for people who still misunderstand the topic. That is why documentation is usually useless for beginners. Documentation for pros by pros, often even with topic specific language. Thus useless for beginners. Stackoverflow is concept error filter feeding. Search -> Do you actually mean -> better Wikipedia -> duplicate of actual answer using specialist prose.
vivekd 3y ago
Mostly yes, there are exceptions. I thought Django and express.js were both well documented. Baseline code also seems to be well documented as a rule. However modules in a lot of languages, even important widely used modules are too often very poorly documented.

20 points by rrreese 3y ago

Sadly the docs are error messages are not seen as part of the product and something that is needed to make something complete. Shipping fast and constantly adding new features has pushed good documentation to the backseat. It’s something that’s nice to have, but almost no one prioritizes, so it never gets done. From what I’ve seen, it is also something that comes with a mature team, as some stability is needed before a team starts to talk about documentation and standards. The constant churn of teams hurts documentation and error messages a lot. Why bother documenting or writing good errors if you won’t be around in 2 years to deal with it? More people need to stick around long enough to feel the pain of their bad decisions and laziness.

mangamadaiyan 3y ago
> Shipping fast and constantly adding new features has pushed good documentation to the backseat I'd just like to add -- shipping fast and constantly adding new features has pushed _almost everything else_ -- including design, and product quality -- to the backseat. Design documents are a rarity these days, forget about well-written and well thought-through design documents.

floxy 3y ago

Is anyone trying to use LLMs to generate documentation?

karmakaze 3y ago

In my experience, the docs are fine and mostly better than a random SO answer. A reason many people use it is because they're lazy or want to get past their hurdle with a quick answer rather than understanding things beyond their current issue. Any time I run into one of these, I'll post a reference to the actual docs as a comment in the top/accepted answer.

db48x 3y ago
Agreed. So many of the people who ask questions on the Emacs stackexchange have never even looked at the manual. Emacs has excellent documentation, and often there will be a whole chapter dedicated to answering that specific question. The title of the chapter will have the same key words as their question. And the manual is readable right inside Emacs! But by asking the question on SE, they can get someone else to go to the trouble of doing a keyword search on the table of contents to find the relevant chapter, then paste in the first paragraph of that chapter. It's laziness, pure and simple.
- egberts1 3y ago
  Excellent documentation? For Emacs? There is such a thing as overloaded and non-user-centric documentation that is rich in details (if you already knew a few Emacs-type keywords)
  - db48x 3y ago
    The Emacs documentation really is quite good. It is user–centric, as you say, starting by naming the things the user can see and interact with when they run Emacs (the menu bar, the tool bar, etc, etc) before going on to more complex topics, such as how commands are given via the keyboard or mouse. While it is detailed, it can hardly be called overloaded. The real reference material is in a completely different book, the Emacs Lisp Reference Manual. There is also a FAQ, and if you’ve never programmed in Lisp before then there is the Emacs Lisp Intro. Then there are something like 60 other manuals for various packages that come with Emacs, like Org Mode or the calculator. These all serve to keep the core manual from becoming overloaded with details. You can read them all online at <https://www.gnu.org/software/emacs/manual/ https://www.gnu.org/software/emacs/manual/>, should you care to try to prove me wrong. I estimate that about 30% of questions on the Emacs StackExchange can be answered by quoting from that core manual, another 20% by the FAQ, 20% by the Elisp Intro, the Reference, or the docstrings of individual commands, and another 10% by the manual for Org Mode. The calculator comes up occasionally too. Perhaps 10–20% of the questions on the site are actually interesting questions that require real thought or a look at the source code.

3seashells 3y ago

If you can search it in the docs, you already know the question well enough to answer. Stackoverflow has answers for people who still misunderstand the topic. That is why documentation is usually useless for beginners. Documentation for pros by pros, often even with topic specific language. Thus useless for beginners. Stackoverflow is concept error filter feeding. Search -> Do you actually mean -> better Wikipedia -> duplicate of actual answer using specialist prose.

vivekd 3y ago

Mostly yes, there are exceptions. I thought Django and express.js were both well documented. Baseline code also seems to be well documented as a rule. However modules in a lot of languages, even important widely used modules are too often very poorly documented.