Ckeditor5: Add screenshots to npm readmes (?)
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
wwalc
All 13 comments
One thing to research first – where to host those images. Can they be stored in repositories or does GitHub disallow hotlinking?
Reinmar
on 14 Sep 2018
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.
Reinmar
on 14 Sep 2018
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.
wwalc
on 14 Sep 2018
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:
dkonopka
on 17 Sep 2018
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
on 17 Sep 2018
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
Reinmar
on 17 Sep 2018
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.
AnnaTomanek
on 17 Sep 2018
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 notifications@github.com 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.
Reinmar
on 17 Sep 2018
(...) 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
dkonopka
on 17 Sep 2018
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
on 17 Sep 2018
Anyway, take a look at fixed screenshots, if you are ok with them I'll prepare a PR.
👍
Reinmar
on 17 Sep 2018
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
wwalc
on 18 Sep 2018
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.
dkonopka
on 18 Sep 2018
Related issues
hybridpicker
·
3Comments
metalelf0
·
3Comments
MCMicS
·
3Comments
Reinmar
·
3Comments
jodator
·
3Comments
Most helpful comment
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:
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:
(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.