I've been trying to get better about just helping to fix the documentation when its bad- but that is dependent on me being able to figure it out in the first place with broken/poor docs.
WTFM - Write The Freaking Manual
41–50 of 82 posts
Re: WTFM - Write The Freaking Manual
#42I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
Why is the Python documentation terrible in this respect? Python comes with a language reference[1], that has most of the components you ask for (one of the components is in a document that's called something other than the language reference, but that's because it's the stdlib, not the language itself... it's certainly the same style of document, not a tutorial!): 1. Syntax (sections 5, 6, 7 and I guess also 9 if yo…
I program in Ruby most days.
A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed.
So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python libraries. There didn't appear to be the equivalent of RubyGems or Bundler. There did seem to be 2-3 different ways of managing them (eggs?), but just getting those programs working on my local system wasn't liking me either. Googling for "Using Python libraries" didn't return much useful- nor did "Installing Python Libraries".
I'm still unclear what the standard method for managing these is. When I checkout a Ruby thing, I just type 'bundle install' and all is fine then.
Yes, the technical docs were fine- but the baseline "how do I get this damn stuff, working!?!?!" wasn't.
Re: WTFM - Write The Freaking Manual
#43Earlier quoted context omitted.
Why is the Python documentation terrible in this respect? Python comes with a language reference[1], that has most of the components you ask for (one of the components is in a document that's called something other than the language reference, but that's because it's the stdlib, not the language itself... it's certainly the same style of document, not a tutorial!): 1. Syntax (sections 5, 6, 7 and I guess also 9 if yo…
I program in Ruby most days. A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed. So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python librar…
There are various methods for installing 3rd party python libraries from PyPI [1], including easy_install, pip, or just extracting the tarball from PyPI and running `python setup install`.
1: http://pypi.python.org/pypi
Edit: There's also the official documentation page called "Installing Python Modules" which covers the last of those three methods: http://docs.python.org/install/index.html
Edit 2: and from the FAQs, http://docs.python.org/faq/library.html#general-library-ques...
Re: WTFM - Write The Freaking Manual
#44I agree - I often just give up and read the source to figure out how to use advanced features.
Re: WTFM - Write The Freaking Manual
#45And while we're at it: Javadoc is not a substitute for writing documentation.
Re: WTFM - Write The Freaking Manual
#46I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
I agree 95%. However, I really do like to see a lot of simple examples. They can often make things much easier to understand once you see it. Similar in concept to "A picture is worth a thousand words".
Re: WTFM - Write The Freaking Manual
#47When it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don't like at all. Guess which I am going to pick. The times when I've actually ended up writing some docs, I don't think anyone has ever read them. And writing the docs is just the beginning, they have…
1. Figure out a way to get paid for it.
2. If you're designing tools for other people to use, documentation really, really, really matters. Even if it's just a mailing list and wiki initially.
When I'm evaluating tools, I look to the docs, and if I find them lacking, my interest dims very, very rapidly. I'm a systems admin, and don't do much coding (though programmers have a need for docs as well). My main concerns are uptime, reliability, predictability, and well-understood behavior. If a tool shows a wild cowboy shoot-from-the-hip, damn the torpedoes mentality, it's going to make my life (and my sleep quantity and quality) hell.
Life's too short for that shit.
Re: WTFM - Write The Freaking Manual
#48I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
I don't see how Python docs are terrible. Any doc is a help() away from you on any REPL.
Re: WTFM - Write The Freaking Manual
#49I fully endorse this. Coming from a sysadmins / devopps perspective, documentation is key to providing a reliable, dependable, available, scalable service. And dramatically improving the quality of my life.
How that documentation is written also matters. A lot.
Much proprietary documentation is also crap, for numerous reasons. Marketing having too much say is key (every reference to a Trademarked(r) Name(tm) Phrase(c) is both fully expanded and badged. Might keep the marketers and lawyers happy, but it's hell to read. Descriptions are vacuous to the point of idiocy ("More magic: select this option to enable more magic") -- tells me absolutely nothing not inherent in the control, and in particular, fails to tell me what the effect of enabling "more magic" is (feature name changed, but this construct is all too common in docs).
Usage notes and examples are mandatory.
As much as Free Software docs are pilloried, I still find that they tend to compare favorably with non-free docs.
Noted here: https://plus.google.com/104092656004159577193/posts/bLaDaXNe...
Re: WTFM - Write The Freaking Manual
#50Earlier quoted context omitted.
Conversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library. Sorry, if you don't have documentation, even a little bit, you're just not worth my time. There are at least two other libraries out there with better documentation. The fact they might be worse software doesn't even matter because all I'm looking for is a solutio…
GitHub READMEs are an excellent compromise. Doing more detailed docs are quite a lot of effort (that is better spent coding), especially to projects that are at an early stage. Projects which are an early stage (like most of my projects) should mostly try to attract potential contributors, not just consumers/end-users so it's not unreasonable to require would-be users/contributors to walk the extra mile and actually…
Even very early alpha code can find its way into production systems. I'm familiar with a case involving a three-letter household name company a few years back using early releases of cassandra, as well as nginx (not entirely beta at that point, but with much of the documentation still in Russian).
Engineering making it work was a long way from operations making it reliable and understood.