Free-programming-books: Consistency of listings (help wanted)

Created on 21 Oct 2020  ·  5Comments  ·  Source: EbookFoundation/free-programming-books

with the flood of additions during Hacktoberfest, I'm seeing some sites/publisher/platforms added where links are inconsistently presented.
One example is books by goalkicker.
Most of our goalkicker listings look like this:
* [Spring Framework Notes for Professionals](https://books.goalkicker.com/SpringFrameworkBook) - Compiled from StackOverflow documentation
This give readers an idea of what to expect, and provides proper attribution. But not all our goalkicker links are formatted the same way.

Similarly, wikibooks links have been inconsistent - there's already a PR working to address that. #4230

Our course listing have expended a lot, and platform attribution has been inconsistent. It should be:
`* title as given by resource - Instructor/Creator (platform)

PR's to improve consistency will be welcomed.

PR requested discussion help wanted

All 5 comments

@eshellman I also noticed this inconsistency as well, would mentioning the platform as "YouTube" be necessary or is it implied if not mentioned? Similar to some links having "HTML" added to them but one could assume that it would be HTML else specified (e.g. PDF, EPUB, etc).

@SethiPandi what do you think?

You may have noticed from how long all my replies are, but I've always been a fan of verbosity and disambiguation.

I feel it's always nice to be explicit, even for things a sensible user may infer, especially as there is no guarantee all users will be sensible.

The only arguably inferable thing in my opinion is HTML, but even then I think it's ideal, though it doesn't have to be mandatory, to specify it. I'm unsure where YouTube may be considered inferable, though.

_The following only represents my personal experience, not the average user._
I say this as someone that personally expected all books to be PDFs until I realized most in fact weren't PDFs at all. (I prefer to read offline in KOReader.)
Of course, I know this _now_, but not as a person that was new to the repository and wasn't familiar with the conventions.

We can elide 'YouTube' and 'Github" from listings. For courses, the platform name is more useful because platforms provide more varied experiences and may have registration requirements.

'HTML' should be indicated only when it is the only format available - often our link lead to a web page which offers links to content of multiple types.

@eshellman okay great that sounds good

We need to compile provider-specific consistency notes. So...

Please add the "Compiled from StackOverflow documentation" attribution we use for goalkicker books
For youtube, we prefer "playlist" links and the name of the producer/creators

from PRs:
MIT OpenCourseWare #5087
Wikibooks #4230
udacity #3880
leanpub

Was this page helpful?
0 / 5 - 0 ratings

Related issues

iamsubhranil picture iamsubhranil  ·  6Comments

kaleemullah360 picture kaleemullah360  ·  8Comments

fosslinux picture fosslinux  ·  5Comments

eshellman picture eshellman  ·  18Comments

aminought picture aminought  ·  15Comments