Feedback Wanted: how are the docs?

[rbuchberger]

The documentation makes sense to me, but I'm incapable of seeing it from the perspective of a new user. What are your pain points? What doesn't make sense? What things are surprising or unexpected?

[ftruzzi]

Hi! Thanks for asking and for making the plugin :)

The docs are clear but quite technical, and not being very familiar with all the features of CSS it took me a while before I understood how to use jekyll_picture_tag properly and before I figured out it was actually able to do what I wanted to. I also had to read a few CSS docs in addition to the guide that is linked here. I think a few visual, practical examples would help with this. Making what the plugin can and can't do visually clear would make sure users don't leave because they don't know if the plugin can help them (or worse, because they mistakenly think it can't).

I think examples of specific use cases (at a wider level) could also be added. For example, one use case is having images of different widths according to the device type (using media_presets), and to have them centered when they end up being smaller than the whole viewport. How do you center them? And what if you want captions as well?

I understand this might also depend on the theme being used, so instructions on how to use the plugin with popular themes would also be nice (I'm using minimal mistakes, for example).

[rbuchberger]

Thanks for the feedback! I like your ideas. I had considered adding a 'how do I?' section that's more workflow based, rather than the itemized list of settings and arguments we have now.

I've always considered CSS and such to be outside the scope of the plugin; it's entirely concerned with building HTML and associated images. That said, it doesn't mean I can't give some assistance in making things work the way you want them to!

[kslstn]

Thanks from me too! I find the docs much better than many other plugin’s. What I found difficult the first time I used it:

• Understanding how picture and image tags work together. Linking to the MDN articles on this would suffice. It’s required knowledgeable, but users need to know that it’s required.
• I forgot what property precisely but I believe that padding-bottom is in browser defaults for picture tags. That confused me when positioning the images.
• Choosing useful output sizes. I still find it a messy process.
• For Jekyll 4 I had to add a specific version of the plugin to my gemfile. I don’t know if that’s still necessary, but it’d be essential for new users.

[rbuchberger]

I've actually been considering typing up a blog post and maybe recording a video explaining responsive images. It's not an easy subject to understand, and the MDN docs aren't amazing.

With padding-bottom, are you talking about a way to set an aspect raio for lazy-loaded images (preventing page reflow)?

By output sizes, do you mean image widths or the actual HTML sizes attribute? I agree it's not easy, but it also doesn't need to be perfect.

I'll verify the installation instructions with a few different versions of Jekyll to ensure they're accurate, and update as necessary. Thanks for the heads-up!

[kslstn]

Sorry for being vague with 'padding-bottom'. I checked my CSS and I haven't properly documented it, but I believe setting picture{ font-size: 0; } was necessary to avoid spacing between the border of <picture> and <img>, but only for some browser(s). Probably a tiny detail that has very little to do with the actual plugin.

By output sizes, do you mean image widths or the actual HTML sizes attribute?

I mean the image widths. In same cases, my images are set with a fixed width (let's say 100px), but a media query changes that width to another size depending on the viewport (let's say 150px). To support multiple retina resolutions, do I now add config for 100px, 200px, 300px and 150px, 300px, 450px? Or do I write 100px, 150px, 300px, 450px? The double listing of 300px bothers me in the first example, but in the second example it's hard to understand where the values even come from. And how to do it sensibly for pictures that are shown in a fluid layout?

For Jekyll 4 I had to add a specific version of the plugin to my gemfile. I don’t know if that’s still necessary, but it’d be essential for new users

I'm back at my computer to check and I had gem 'jekyll_picture_tag', '~> 1.6' in my gemfile with Jekyll 4.0.0. But I removed the ''~> 1.6'bit, didbundle update` and now it works fine with version 1.9.0! Sorry about that too.

[stuntbox]

Sorry for being vague with 'padding-bottom'. I checked my CSS and I haven't properly documented it, but I believe setting picture{ font-size: 0; } was necessary to avoid spacing between the border of and , but only for some browser(s). Probably a tiny detail that has very little to do with the actual plugin.

@kslstn It sounds like you may be describing the default inline behavior of img elements and how they handle surrounding whitespace?

[kslstn]

@kslstn It sounds like you may be describing the default inline behavior of img elements and how they handle surrounding whitespace?

Yes! That was it. Because all my images are in an article and my article is a flex box, I initially couldn’t explain why an img inside a <picture> was different. Also had something to do with my confusion about what elements inside the picture are visible (not <source>).

[kslstn]

Yesterday I was looking for allowed values for properties in presets and couldn’t find them. I also found the division between media presets and markup presets not totally clear. When I understand it right, media presets are only used within markup presets, but they’re described as almost equally important.

[ImaCrea]

Well, I'm a bit lost on installation :/ Don't know if it's coming from doc being quiet concise there of from my system (check issue I just created) Thanks for everything!

[rbuchberger]

I suppose I should be aware that not everyone using JPT has much experience with Gemfiles! Thanks, I'll try to make it more clear.

[InfamousStarFox]

Adding something about keep_files for the generated folder in /_config.yml file would be nice

[leecalvink]

I mean the image widths. In same cases, my images are set with a fixed width (let's say 100px), but a media query changes that width to another size depending on the viewport (let's say 150px). To support multiple retina resolutions, do I now add config for 100px, 200px, 300px and 150px, 300px, 450px? Or do I write 100px, 150px, 300px, 450px? The double listing of 300px bothers me in the first example, but in the second example it's hard to understand where the values even come from. And how to do it sensibly for pictures that are shown in a fluid layout?

I am confused by this as well. In my case I have 1 breakpoint where the image is a certain max width below, and a certain max width above. I want to provide retina images for both cases. Do I need to specify two different media presets with their own settings in _data/picture.yml, then reference them both like this {% picture mobile: "image.png" desktop: "image.png %} ?

[rbuchberger]

Hey all, sorry I've neglected this topic. The feedback here is awesome, and I'm planning to overhaul the docs based on it after I push this next update.

Shower thought: media_presets and markup_presets are bad names; media_queries and presets would be much better. To make the switch we can keep the old names working and just print a warning to the console, until we release a new major version (if that ever happens). Any objections?

@leecalvink & @kslstn - sorry for the delayed answer! I'll definitely devote some words to the subject in the new docs. The key here is to remember that the browser is smart; if you set a good sizes attribute, it will pick the best-fitting image on its own. In your example, I'd definitely say use 100, 150, 300, and 450. Remember that there are plenty of devices with pixel ratios other than 1, 1.5, and 2, so you're never going to hit the right sizes down to the pixel. We're just trying to get reasonably close.

@InfamousStarFox - JPT automatically enables that setting at runtime; you shouldn't have to do anything with it. Is that not your experience? Or are you asking for an option to disable that functionality?

[rbuchberger]

Update: Just pushed a big overhaul of the docs. I haven't finished with all the suggestions here, so I'll keep this issue up. Feedback is still encouraged!

[ImaCrea]

Great stuff!! Wow :) Thanks :) ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

…

On Wednesday 29 July 2020 18:34, Robert Buchberger ***@***.***> wrote: Update: Just pushed a big overhaul of the docs. I haven't finished with all the suggestions here, so I'll keep this issue up. Feedback is still encouraged! — You are receiving this because you commented. Reply to this email directly, [view it on GitHub](https://github.com/rbuchberger/jekyll_picture_tag/issues/170#issuecomment-665770344), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/AAF2TLAIVYSN2LBCKXTI6ATR6BFQPANCNFSM4KTAT3LQ).