Add screenshots to npm readmes (?)

[wwalc]

There is a chance that with screenshots npm readmes would look even better:

• https://www.npmjs.com/package/@ckeditor/ckeditor5-build-classic
• https://www.npmjs.com/package/@ckeditor/ckeditor5-build-balloon
• https://www.npmjs.com/package/@ckeditor/ckeditor5-build-inline
• https://www.npmjs.com/package/@ckeditor/ckeditor5-build-decoupled-document

[Reinmar]

One thing to research first – where to host those images. Can they be stored in repositories or does GitHub disallow hotlinking?

[Reinmar]

The readme we've got on https://github.com/ckeditor/ckeditor5 is hosted on our CDN so maybe we'll need to go this way.

[wwalc]

CKEditor 4 holds the screenshot in a dedicated assets folder: https://github.com/ckeditor/ckeditor-dev/tree/master/.npm/assets and https://www.npmjs.com/package/ckeditor links to https://raw.githubusercontent.com/ckeditor/ckeditor-releases/HEAD/assets/ckeditor4.png
However the path should be fixed instead of pointing to HEAD.

CC @mlewand as he may have some further comments on their approach.

I don't have any personal preferences.

[dkonopka]

I've reduced height of images by ~30% to save some space in the readmes. WDYT?

Current https://github.com/ckeditor/ckeditor5 image

Balloon proposal:

Classic proposal:

Inline proposal:

PS: Maybe we should think about improving features readmes too?

Highlight readme proposal:

Font family:

[Reinmar]

Font family:

👍

I've reduced height of images by ~30% to save some space in the readmes. WDYT?

I'm not sure. E.g. we make image caption invisible in the classic editor case. I like the current height more.

PS: Maybe we should think about improving features readmes too?

We might... but I'd rather link to a demo instead (which I think we don't do). It says more than this and means less work for us. BTW, we should also check docs/api/<feature name>.md files for the same.

[Reinmar]

Damian made me think about the docs/api/<feature name>.md pages. I see e.g. that in autoformat we link to the feature's page (where there's a demo) but we don't use the word "demo". I'd add another section before ### Documentation with a simple:

### Demo

Check out the demo in the {@link features/autoformat Autoformat feature} guide.

### Documentation

See the {@link features/autoformat Autoformat feature} guide and the {@link module:autoformat/autoformat~Autoformat} plugin documentation.

WDYT? cc @AnnaTomanek

[AnnaTomanek]

Demo links are nice, but images are something far more eye-catching. So I'm afraid I'm +1 about adding screenshots, too :)

See also #1186, #1187.

[Reinmar]

I know. But that’s far more for us to maintain. Imagine changing the skin. 30 screenshots more to update. Plus, how would you show some features like auto format? Plus, who will create those? For the above posted ones we needed Damian or Oleq. It’s just quite a cost for something that we have a link from you in the demo.

…

Sent from my iPhone

On 17 Sep 2018, at 14:20, Anna Tomanek ***@***.***> wrote: Demo links are nice, but images are something far more eye-catching. So I'm afraid I'm +1 about adding screenshots, too :) See also #1186, #1187. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[dkonopka]

(...) I'd rather link to a demo instead (which I think we don't do). It says more than this (...)

I don't agree with this, clicking the demo url is an additional action for user and a lot of them doesn't use/see it. Of course is time-consuming for us, but still, we should think about it.

Anyway, take a look at fixed screenshots, if you are ok with them I'll prepare a PR.

Balloon build

Classic build

Inline build

Decoupled build

[Reinmar]

I don't agree with this, clicking the demo url is an additional action for user and a lot of them doesn't use/see it. Of course is time-consuming for us, but still, we should think about it.

And so we are thinking :D What we need to focus on is the ROI. It's clear that screenshots are great and say more than 1000 words. Still:

• We need to consider how many people visit pages of those packages on npm/GitHub. When you search for "CKEditor 5 alignment" in Google you get the link to https://github.com/ckeditor/ckeditor5-alignment first (followed by a link to https://ckeditor.com/docs/ckeditor5/latest/features/text-alignment.html; npm is ~10th). However, the GH page has only 10 unique visitors daily (count us out and it's a negligible number). https://ckeditor.com/docs/ckeditor5/latest/features/text-alignment.html has a lot more, plus, I think that it's safe to assume that most of the people who've seen the GH page will also see the doc page (in the README there's a link to http://ckeditor.com/docs/ckeditor5/latest/api/alignment.html and this page has quite a lot of visits).
• Maintaining screenshots, especially those which require graphical post-processing, is costly. We've learnt that many times. It's easy to make a lot of them, but the maintenance can be frustrating. As a result, we often had outdated screenshots which isn't that good either.
• A person who already looks for a certain CKEditor 5 feature already considers using CKEditor 5 so there's a bigger chance that he/she will spend on searching for the feature more than 3 seconds.

Taken the above into account, I say – no screenshots, please. Unless we can automate making them (possible, but future), that's a big cost and a low ROI.

However, we still have a problem – you can't quickly get to a demo from https://github.com/ckeditor/ckeditor5-alignment. There's no link to either this feature's documentation or, better, the demo itself. And that' something we can improve.

That's why on GitHub, npm and in API docs I'd use such a text:

### Demo

Check out the demo in the {@link features/autoformat Autoformat feature} guide.

### Documentation

See the {@link features/autoformat Autoformat feature} guide and the [`@ckeditor/ckeditor5-alignment` package](https://ckeditor.com/docs/ckeditor5/latest/api/alignment.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).

(with slight adjustments in certain cases)

Thanks to how clear the readme is, a person who's checking out this feature will have no problems with finding the demo.

[Reinmar]

Anyway, take a look at fixed screenshots, if you are ok with them I'll prepare a PR.

👍

[wwalc]

Just $0.02 about screenshots - I personally don't like screenshots with selection, unless it's really needed for showcasing something. It's a little bit confusing with the highlight feature. I personally prefer showing just the collapsed selection somewhere (at the end of header).

No need to rework screenshots, just checking if others share my preferences (for the future or sth) or if I'm alone :D

[dkonopka]

Hmm.. I did it intuitively 😄plus don't have any preferences which version is better ;)

Anyways, I just realised that screenshots need an update because of missing table & media-embed(?) features.