Library Writing Realizations (2015)(cbloomrants.blogspot.com)
cbloomrants.blogspot.com
Library Writing Realizations (2015)
http://cbloomrants.blogspot.com/2015/09/library-writing-realizations.html
14 comments
That's another thing not to do when writing a library: including and discussing code examples of incorrect usage. Personally, when I read documentation, retaining incorrect code examples is literally the last thing I want to achieve.
The python csv reader shows off how it can parse non standard nonsense csvs like csv.reader(csvfile, delimiter=' ', quotechar='|')
https://docs.python.org/3/library/csv.html
Of course most readers who copy paste this garbage will be first confused by the results and then will find the actual answer on stackoverflow
https://docs.python.org/3/library/csv.html
Of course most readers who copy paste this garbage will be first confused by the results and then will find the actual answer on stackoverflow
My hypothesis is that people who write code for fun don't read docs and people who do read docs are the types to 'about' things rather than 'do' things.
The list is pretty good, although I am still in favor of good docs since software is not only supposed to be used, it's also there to be studied by future people who want to learn new ideas.. I loved reading manuals for programming languages for more than a decade, but now I am a bit bored with the genre, writing software has also become a bit more fun than before... I'm sure these things correlate.
The list is pretty good, although I am still in favor of good docs since software is not only supposed to be used, it's also there to be studied by future people who want to learn new ideas.. I loved reading manuals for programming languages for more than a decade, but now I am a bit bored with the genre, writing software has also become a bit more fun than before... I'm sure these things correlate.
I remember reading this back in the day. It put what I was doing into words better than I could
> X. People will not read the docs.
> Docs are almost useless. Nobody reads them.
> They'll read a one page quick start, and then they want to just start digging in writing code.
> Keep the intros very minimal and very focused on getting things working.
I, for one, read the docs. May fortune smile on those who put effort into https://rasterio.readthedocs.io/
They are terse, but enough breadcrumbs to fumble my way to a working input for gdal_proximity.py
Possibly I'm not a representative sample, but one of my mantras at the office is "If you ain't doc'in', you ain't rockin'."
(Though we are only doing ransom note wiki pages, not library documentation.)
If the package doesn't have shiny Sphynx docs, at least afford us a few cryptic utterances in the source code.
> Docs are almost useless. Nobody reads them.
> They'll read a one page quick start, and then they want to just start digging in writing code.
> Keep the intros very minimal and very focused on getting things working.
I, for one, read the docs. May fortune smile on those who put effort into https://rasterio.readthedocs.io/
They are terse, but enough breadcrumbs to fumble my way to a working input for gdal_proximity.py
Possibly I'm not a representative sample, but one of my mantras at the office is "If you ain't doc'in', you ain't rockin'."
(Though we are only doing ransom note wiki pages, not library documentation.)
If the package doesn't have shiny Sphynx docs, at least afford us a few cryptic utterances in the source code.
The first step in vetting a new dependency for me is always documentation (not just taken at face value but also how well it corresponds to reality). The more complex the functionality and the larger the scope, the more it matters.
First, since writing a library is a lot about design, and design is about communication, documentation provides many indirect but useful signals. Second, no project (whether dev-to-dev or dev-to-end-user) exists at a discrete point in time, and as every piece evolves documentation will be critical for making it manageable, especially if the project is not something done for hire.
First, since writing a library is a lot about design, and design is about communication, documentation provides many indirect but useful signals. Second, no project (whether dev-to-dev or dev-to-end-user) exists at a discrete point in time, and as every piece evolves documentation will be critical for making it manageable, especially if the project is not something done for hire.
I read the docs too. Great docs can spell the difference between using your code and giving up or finding another solution. If you're new to a particular language or programming, code with great docs can also teach you how the language itself works.
Tabulator (http://tabulator.info/docs/5.3) is the last example that comes to mind, had to use it earlier this year.
Tabulator (http://tabulator.info/docs/5.3) is the last example that comes to mind, had to use it earlier this year.
Even when people don't read the docs, it's often not a matter of unwillingness to - but them not expecting relevant docs to exist in the first place, or being unable to find them with the keywords they can think of.
Being able to link said docs saves on having to re-explain everything from scratch when asked questions - helping contextualize and give background to a terser answer, assuming the docs don't answer the problem outright. They can also be helpful to refresh my own memory when explaining things, or when I'm trying to remember how to use my own code.
Being able to link said docs saves on having to re-explain everything from scratch when asked questions - helping contextualize and give background to a terser answer, assuming the docs don't answer the problem outright. They can also be helpful to refresh my own memory when explaining things, or when I'm trying to remember how to use my own code.
I wonder if he has hard data about how often people look at his documentation.
I generally agree with everything he wrote. One page quick start, focus on getting things working, people will dig into writing code right away. Yes, yes, yes. But, then what? People tend to read documentation extensively when something doesn't work the way they think it should. You can make your API as self-documenting as humanly possible, but there's no way to know if the person using your API is going to be on the same wavelength.
My go-to example here is Ruby. I once got stuck on an interactive ruby tutorial because you're supposed to be able to guess the names of the commonly used functions in ruby. This particular tutorial wouldn't let you pass until you figured it out. I had to google it. For whatever reason, it was not the word I would have chosen. The word they chose makes complete sense in hindsight, but it's simply not the word that comes to mind to me.
I kept running into that again and again with Ruby and later with Rails. I just wasn't getting it. The documentation became very important for me to get anything done.
I generally agree with everything he wrote. One page quick start, focus on getting things working, people will dig into writing code right away. Yes, yes, yes. But, then what? People tend to read documentation extensively when something doesn't work the way they think it should. You can make your API as self-documenting as humanly possible, but there's no way to know if the person using your API is going to be on the same wavelength.
My go-to example here is Ruby. I once got stuck on an interactive ruby tutorial because you're supposed to be able to guess the names of the commonly used functions in ruby. This particular tutorial wouldn't let you pass until you figured it out. I had to google it. For whatever reason, it was not the word I would have chosen. The word they chose makes complete sense in hindsight, but it's simply not the word that comes to mind to me.
I kept running into that again and again with Ruby and later with Rails. I just wasn't getting it. The documentation became very important for me to get anything done.
> I wonder if he has hard data about how often people look at his documentation.
Context: He works for RAD Game Tools, now a subsidary of Epic Games, and worked on the Oodle data compression suite for a long time. As such I believe there were tons of direct customers who would contact him and other team members whenever things went hairy. (There were no free version of Oodle so every user is a paying customer or sometimes an evaluator.) Therefore I guess he does have some data but no hard numbers.
Context: He works for RAD Game Tools, now a subsidary of Epic Games, and worked on the Oodle data compression suite for a long time. As such I believe there were tons of direct customers who would contact him and other team members whenever things went hairy. (There were no free version of Oodle so every user is a paying customer or sometimes an evaluator.) Therefore I guess he does have some data but no hard numbers.
Well, that makes two of us. I'll actually just go inspect the source code a lot of the time since docs can be wrong, but the docs are still good in that case to help provide an overview.
What absolutely needs to be present is some sort of index of all functions/data types, ideally with a link to the underlying source code. Don't make people try and guess what your library exposes.
What absolutely needs to be present is some sort of index of all functions/data types, ideally with a link to the underlying source code. Don't make people try and guess what your library exposes.
I read the docs too, though generally a minimally working example / quick start is where I'll stop unless I run into issues.
Even though I'm a prospective developer I read the title as "realizations I had when writing in a public library". I was hoping for tips or insights when working in public spaces.
> People will not read the docs.
Reminds me of a pull request I made a while ago
https://github.com/krisajenkins/yesql/pull/151/files
The first piece of code on the readme is "not the solution" (lol), and everybody I knew who was trying to use that library was copy-pasting that specific piece of code from the readme.