5 ms·
If people are frequently asking the same question then your information and how you deliver it is lacking. You can solve this by making a FAQ, or your can writ
by moksly 5y ago
If people are frequently asking the same question then your information and how you deliver it is lacking.
You can solve this by making a FAQ, or your can write better information.
Having recently moved from Python (where the documentation is amazing) to TypeScript/JavaScript (where the documentation is horrendous) this issue has never been clearer to me. The only Python library that I’ve ever had to go outside the documentation to understand has been pandas. I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions.
It might just be me of course. I never really liked the Microsoft documentation pages either, so maybe I’m just an oddity that can only read Python styled documentation, but maybe not. I mean, why does the Express library have a “security FAQ” which seems like it should basically have been a simple part of the “start here” guide? I’m probably missing something, but reading the security FAQ left me with the feeling you would be an idiot not to use the helmet library with express (at least until you know enough to know when not to use it), and if that is so, then it really shouldn’t be a separate FAQ should it?
I know I went down a side track, but it’s really the most perfect real world example I have of why this article is exactly right.
- retube 5y ago> TypeScript/JavaScript (where the documentation is horrendous) Clearly you've never had to do anything in VBA....
- vbezhenar 5y agoIt's odd but when I have to write something with Python, its documentation really is terrible. There's not even index of functions in particular module, I have to open it, then find that function with ctrl+f. E.g. https://docs.python.org/3/library/os.html https://docs.python.org/3/library/os.html Compare to golang: https://pkg.go.dev/os https://pkg.go.dev/os it provides list of all functions in particular module which I can glance over quickly and find what needed. That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need. And I never had issues with JavaScript thanks to wonderful MDN.
- OJFord 5y agoPython's the main language I've used professionally (i.e. used most by a long shot) and I agree. I think it's just a newer style, newer languages and frameworks seem to have a more structured/hierarchical/indexed style like that IME.
- FooBarWidget 5y agoNewer? If you look at Javadocs, they're highly structured, at least as much as — and arguably more so than — Go docs. I think it has got more to do with culture and tradition. Each language seems to have its own documentation culture. Python seems to favor docs in which structure is interleaved with prose. I find Go docs to be pretty hard to make sense of. Often times they don't explain very well how to use a package. And browsing around different aspects of a library carries a feeling of obscurity. Ultimately, I think documentation should be split up into multiple categories, ala https://documentation.divio.com/ https://documentation.divio.com/
- noisy_boy 5y agoThe best example of being lost in docs is Python's re (regex). Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. If I have a specific requirement or want the gory details, I can always scroll down.
- bmn__ 5y ago
- rhaksw 5y ago> If people are frequently asking the same question then your information and how you deliver it is lacking. I maintain a FAQ mostly for things over which I have no control, https://www.reveddit.com/about/faq/ https://www.reveddit.com/about/faq/ Each question comes from a user's comment somewhere, and I often link back to it when answering new questions. I'd be interested to hear if people would prefer a different format or different wording.
- jaclaz 5y agoYep, but those are actually Frequently Asked Questions, what I cannot bear is the use of FAQ (and their page) on a brand new site, where there has not been time enough for any "real" question to have been asked by the user. It is only a (poor) literary form and since they are (mostly) prefabricated, they are either unneeded/duplicated (as the topic is properly explained in the main site/docs) or actually showing that the original text/docs/instructions are not clear enough (and since the Author has control on those, they could be rewritten/amended/corrected to make them more clear). And - more correctly - they should be FGA's: https://web.archive.org/web/20201231033026/https://jdebp.eu/FGA/ https://web.archive.org/web/20201231033026/https://jdebp.eu/... https://web.archive.org/web/20201231033031/https://jdebp.eu/FGA/fga-not-faq.html https://web.archive.org/web/20201231033031/https://jdebp.eu/...
- adwn 5y ago> Having recently moved from Python (where the documentation is amazing) Huh? Python's online documentation is horrible. In addition to what vbezhenar said, there are gems like this: The arguments shown above are merely the most common ones, described below in Frequently Used Arguments (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - most of the arguments to this function are passed through to that interface. (timeout, input, check, and capture_output are not.) [1] "Largely the same"? What, am I supposed to divine the actually available parameters? For built-in types, the docs are missing a way to quickly list all available methods and properties. You have to somehow piece it together from various ABCs. [2] Compare this to, e.g., Rust's online doc of its Vec type. [3] [1] https://docs.python.org/3/library/subprocess.html#using-the-subprocess-module https://docs.python.org/3/library/subprocess.html#using-the-... [2] For example, lists: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range https://docs.python.org/3/library/stdtypes.html#sequence-typ... [3] https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html
- lupire 5y agoit says it rifht there: "timeout, input, check, and capture_output are not." For everything else, you have to consult Popen because it's Popen's API.
- zestyping 5y agohelp(list) quickly provides a list of all available methods and properties, as does help([]). Is that what you mean?
- adwn 5y agoI was refering to the online documentation. Yes, the interactive docs are sometimes better.
- lobocinza 5y agoPython documentation is not amazing. Search is poor, I expect nowadays instant structured search. Table of contents is generally useless. And important information like common usage is not displayed upfront. Python docs might be great for learning concepts for the first time but not for quickly consulting stuff.
- camillomiller 5y agoThis isn't true. All sort of people - even the most incentivized to find out a specific information - benefit from a sort of short summary in the form of a FAQ section. Sure, some can see FAQ as a patch, but I don't see how they can't be a valuable addition even to a well laid out website where information is easily accessible. The two things aren't mutually exclusive.
- ozim 5y agoFor me biggest issue are synthetic FAQs because they don't really offer anything that documentation would not. Worst offenders are when CEO tells some intern that they need FAQ on the page so that people can see that other people are asking questions about product ;) Ideal FAQ lets you search or has questions in a way real person would ask, as those should be written down in a way most people asked such questions. We could even have index of multiple forms of the same question pointing to the right answer. Problem with documentation is that it is not written there to answer questions. It is written from perspective of "how system works" so someone just writes it down. For technical documentation like a language I don't expect much need for an FAQ because audience should be able to pose questions and answer those by themselves and then search what is provided like a manual. For web application or government websites that general audience should use I don't see "documentation" approach viable, you need "Questions and Answers" approach.
- trutannus 5y ago> I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions Reading unit tests for me has been my go-to for getting around problems in TS/JS documentation in libraries. Unit tests can sometimes be unintentionally the best documentation. Also helps filter out quickly libraries you'd want to avoid at all costs. No unit tests means you're putting untested code into your system.