[HN Gopher] Library Writing Realizations (2015)
___________________________________________________________________
Library Writing Realizations (2015)
Author : luu
Score : 16 points
Date : 2022-07-24 20:43 UTC (2 hours ago)
(HTM) web link (cbloomrants.blogspot.com)
(TXT) w3m dump (cbloomrants.blogspot.com)
| smitty1e wrote:
| > 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.
| PainfullyNormal wrote:
| 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.
| lifthrasiir wrote:
| > 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.
| slaymaker1907 wrote:
| 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.
| timakro wrote:
| 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.
___________________________________________________________________
(page generated 2022-07-24 23:00 UTC)