[FM Discuss] issues with Kdenlive manual images

M R matrobnew at hotmail.com
Mon Feb 12 18:47:28 PST 2018


Martin:


That sounds really interesting: I didn't know you could specify by viewport h and w % in CSS (though that's standard in lots of app authoring I've done, for e.g. Windows or Android apps).   But then I know next to nothing about modern CSS; I basically got out of client-side web development as such in the early '00s.


Mick, what do you think?  To *some* degree it seems like going with viewport width (and height) % would address our issues--but then again, perhaps not completely.  If I put in a 1300 px wide screenshot and our CSS, revised along the lines Martin suggests, rendered that as (say) 80% of someone's 800-pixel width screen, then the image would all fit in their screen, but the details would be tiny, probably too tiny to be useful.  So we might still need some absolute limit on screenshot pixel width.


The thing is, there is a whole galactic-sized industry of technical writing out there, still cranking out documentation with screenshots (despite my best efforts to move them toward video 😊); so you'd think there would be best-practice guidelines well established around this very question.  You would think.  But in the google searching I've just done, while I've unearthed some very sensible articles/posts from individuals talking about what makes for better and worse screenshots, I get no sense at all of a widely-accepted standard width or resolution.   If those standards are out there, they're embedded in full tech-writing courses and not seemingly accessible to googling.


Everyone I've read agrees that screenshots should be PNG and not JPEG.  Most people agree that PRNTSCRN is too blunt-force, at least without cropping, not least because it will inevitably capture personal screen details that are idiosyncratic and distracting, and irrelevant.  Any tech-writing professional is presumably using some specialized screen capture software that allows for selection of a customized area or a specified app or window (the one I use even tries to pick out specific panes/windows within the software UI I'm demo-ing, which is great when it works).  But none of this speaks to how large (and in what resolution) the captured area actually should be.


The common-sense answer is: "large enough to show what you need to show, ie what is actually relevant to your demonstration."  Mick, that was basically your original answer, and it's truly sound common sense; but then I would go right back to my original response to it.  Maybe where that leaves us is the idea that, if the software you're trying to demonstrate really does require you to see, simultaneously, multiple panes of a UI stretching across, say, 1000+ pixels or more, then perhaps we're beyond the limits of the static text-and-screenshot genre of documentation anyway.   So maybe we just kick the image-width limit up slightly, to 1000 (though that was a purely arbitrary number); or maybe we change the CSS to a % of viewport, but still establish a defacto max width of 1000 for FM screenshots.  Or maybe the de facto standard should remain 800 px.  Truly it beats me.


I'm going to stay below 800 px for the duration of the Shotcut manual, anyway --  even though I'd be truly surprised if many Shotcut users actually confined themselves to that little real estate in using the tool.  Btw, here's some survey data on display sizes and their historical trend, from a pretty established source:


https://www.w3schools.com/browsers/browsers_display.asp


OTOH, the typical FM manual consumer might be a lot more old-school than the median of these trends.


Best,


Matt


________________________________
From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of Martin Kean <Martin.Kean at op.ac.nz>
Sent: Monday, February 12, 2018 5:37 PM
To: discuss at lists.flossmanuals.net
Subject: Re: [FM Discuss] issues with Kdenlive manual images


Hi there,


I'm a little late to the conversation, but wondering if pixels are the best for <img> width within device screens or for the printed page.

I often use vw and vh, viewport width and viewport height:


https://css-tricks.com/fun-viewport-units/


and here ...


https://css-tricks.com/full-width-containers-limited-width-parents/


... but of course the point we want to get to is not having to resort to media queries, or specific stylesheets for print and screen outputs.

I'm really getting into CSS Grid:


https://css-tricks.com/snippets/css/complete-guide-grid/

http://jensimmons.com/post/feb-27-2017/learn-css-grid


... but this would be too long a stride out at this point, so I suggest viewport widths:


img {
       border-style: none;
       border: 0;
       box-sizing: border-box;
       min-width: 80vw;     /* 80% of the screen or page width, or whatever % you prefer */
       max-width: 95vw;    /* again, whatever % you prefer */
       height: auto;
}


I'd like to work with anyone on this so please keep me in the loop.


Thanks, Martin

________________________________
From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of M R <matrobnew at hotmail.com>
Sent: Tuesday, 13 February 2018 10:29:46 a.m.
To: discuss at lists.flossmanuals.net
Subject: Re: [FM Discuss] issues with Kdenlive manual images


Hi Mick:


Well, for my part, I thank you for being so gracious in responding to my often-polemical screeds.  That's kind of how I  process what I learn -- and working on the Floss manuals has been a huge learning experience for me -- but some of it should probably just be saved for my cat.  She's used to it.


The image-width constraint has been a challenge, but a productive one, as I start working through the how-to chapters of the Shotcut manual.   I'm managing so far.  I'm sure there are all kinds of feature benefits in moving to Booktype 2.x, but I'm sure it's a hassle too.


As far as changing the global css override for image width in our current Booktype: seems like a lot of factors to consider there.  One, how do modern browsers process the css implemented there -- I don't know nearly as much about that as some people in this community.  Most modern websites are designed to scale gracefully down to very small screen sizes, without scrolling -- especially in the era of tablet and mobile browsing.  But that's typically about how different page elements flow around each other, rather than how a specific large image is handled.  Still, I know that all my browsers (IE, Chrome, Firefox) will automatically scale down a large image to fit my window, in nearly all cases, unlesss I force them to show me the image full-size.


I don't think we're anywhere close, with Booktype 1.6, to being able to produce html content that's in any sense mobile-ready; so really this is a question of how many people are actually accessing the Floss manuals on desktops and laptops with windows set to less than a 800 px or 700 px resolution.  Maybe we could do a survey?  And similarly, how many people are using the print-friendly format (since that would probably remain the real constraint).


best,


Matt


________________________________
From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of Mick Chesterman <M.Chesterman at mmu.ac.uk>
Sent: Monday, February 12, 2018 3:16 AM
To: discuss at lists.flossmanuals.net
Subject: Re: [FM Discuss] issues with Kdenlive manual images


Hi Matt,


Thanks for these thoughtful responses. I can see your point about the advantage of video tutorials for these kinds of complex situations where there are a lot of moving parts.

And you make a good case for looking at different situations and using doc tools based on the most appropriate response.


As far as the screen limit, at the moment, the css override is the following;

img {
       border-style:none;
       max-width:800px;
       height: auto;
}


I would be very up for changing that to increase if we can work out a way of the image size scaling down if people's windows are smaller.


This has been helpful for me to start up conversations to get moved to booktype 2 as well.


Thanks

Mick






From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of M R <matrobnew at hotmail.com>

Sent: 10 February 2018 21:07
To: discuss at lists.flossmanuals.net
Subject: Re: [FM Discuss] issues with Kdenlive manual images


Mick:


I just sent a version of this response with a doc attachment, but the listserve is balking at the size of the attachment as it has multiple screenshots, so here is just the text of my response repeated.  Perhaps the moderator-machine will let my first version with the attachment through in time.  Meanwhile:


I think you raise a valid point, and codifying screenshot guidelines sounds like a good idea; but I also think it just depends utterly on what kind of authoring or editing tool (and what kind of media) we're talking about.  Generally speaking, the more complex the media (or multimedia) being edited or authored, the more likely it is that a UI surface will need to have multiple panes/panels/windows showing different kinds of information, but that really need to be viewed simultaneously (more or less) to get a whole picture of what you're doing in a given operation.   And very little software UI design today, for such editors, assumes that users will confine themselves to anything like an 800 px-wide screen resolution.


Let's consider some concrete examples.  Audio is in some ways the simplest medium, and so with a tool like Audacity, you're for the most part just working in tracks on a linear timeline, so showing just part of that timeline in a screenshot will generally suffice to put across your operation.  And a simple text editor, of course, can pretty much be sized however you want it, within reason.  With code-editors it depends on how feature-rich the UI is.  Static image editors and draw tools, same thing: I think our Inkscape manual does an amazing job of working with probably too-confined real estate.  Photoshop or Gimp would also be a challenge, though I can imagine it.  Something like Powerpoint or comparable slide-deck tools is already pushing the limits for small-screen editing, even of a 'static' product, since slide-decks really aren't static anyway.


For a video editor, that's already much more complex as you have a linear timeline plus a video display, plus typically other panes with important property information.  So far in the new Shotcut manual I've just shown just portions of each of these, which is fine for a walk-through of the different panels but will be a real constraint when I get to the actual 'how-to' chapters.  But I'll do my best.


For a tool to author any kind of multimedia/interactive eLearning material (e.g. Articulate Storyline, Adobe Captivate), you can very rarely get away with seeing just 700-800 px of real estate at once.  Or Flash (now reborn as Animate), or really just about any Adobe-model multimedia authoring product.  For 3D modeling and game-building tools, not a chance.  It's true that you will still want to draw your reader's/viewer's attention to different parts of the UI, to understand what they're about, but to get a sense of real-time operations you need to see the whole.  In these cases there is no such thing as "the most relevant part of the screen" -- it's all relevant.  This is really why video software tutorials almost always show the full software UI, taking up most or all of the presenter's desktop, and are typically now shot in high-resolution and meant to be viewed wide-screen or full-screen too.


I've already indicated other reasons why I think a text-and-screenshot document for a tool like Blender or Unity is pretty pointless.  I'd extend that to many of the other tools I've mentioned here.  Shotcut is probably pushing it, though at least in video editing the number of movingparts is still (somewhat) limited.  Still, if there were simply more decent video tutorials extant for Shotcut, I wouldn't consider it worthwhile to write an FM manual for it.  And setting the moving-parts argument aside, if I were designing a BookType-style platform now, I'd never put in a 700 px hardcoded limit for images, regardless of the target medium, even print.


Attached (in the original, currently-embargoed version) is a doc with me putting my $$ or effort where my mouth is regarding tutorials for a tool like Unity3D.  One can still find book-length text-and-screenshot manuals for Unity too, but to my mind they are entirely pointless.  For Shotcut, though, the effort still seems worthwhile, at least at this stage in the process.  Ask me again in another few weeks.


Best,


Matt




________________________________
From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of mick at flossmanuals.net <mick at flossmanuals.net>
Sent: Saturday, February 10, 2018 5:57 AM
To: discuss at lists.flossmanuals.net
Subject: Re: [FM Discuss] issues with Kdenlive manual images



On 09/02/18 20:16, M R wrote:
> 00 px is a pretty draconian limit for modern screenshots, though, as
> no one in their right might would use most of these editing tools at
> that width.  I get that the print version needs some kind of image
> width limit.  One would think that the "Constrain Proportions"
> function would at least, you know, constrain proportions if the image
> exceeded that limit, and simply show a smaller overall screenshot.
> But I can't get that to work in the editor: it seems to always take
> the actual height but constain the width.  No doubt why they fixed it
> in 2.2...

As Rosalind pointed out, I does seem to do that for the published
version. But I have seen squished images in the editor too.

So maybe we can work on a guideline for images width based on what they
look like when they are outputted to pdf. 800px for me seems about right
as above that it is hard to see what you want users to look at.

For me although the challenge of drawing the attention to the most
relevant part of the screen.

Thanks
Mick
_______________________________________________
Discuss mailing list
Discuss at lists.flossmanuals.net
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net - you can unsubscribe here
Discuss Info Page - lists.flossmanuals.net<http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net>
lists.flossmanuals.net
Discuss anything about floss manuals - its aims, what it does, how it does it, what it could do, and how it can be better. To see the collection of prior postings to ...



"Before acting on this email or opening any attachments you should read the Manchester Metropolitan University email disclaimer available on its website http://www.mmu.ac.uk/emaildisclaimer "
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20180213/8cd058e1/attachment-0001.html>


More information about the Discuss mailing list