orange3 icon indicating copy to clipboard operation
orange3 copied to clipboard

Widget documentation

Open janezd opened this issue 9 months ago • 1 comments

In https://github.com/biolab/orange3-doc-visual-programming/pull/2, @ajdapretnar updated screenshots and some text, following similar contributions by @borondics. This was/is needed and long overdue, but documentation has other issues as well.

  1. It looks awful, in particular because of image scaling: some retina images appear twice the size (or perhaps they are resized to the full width of the column), and some are too wide and squeezed into the column. As consequence, a page for a single widget is a hodgepodge of screenshots in different resolutions, most of them too big or too small.

    I think we should use a style in which the widths of images do not depend on the widths of columns, except for very wide images that would be shown downscaled and expanded on click. We should generally avoid those.

  2. I dislike the general layout (see below). It's just ... ugly, and in part the cause of the problems with images. We can host the docs on github pages and use whatever style we wish.

  3. Terminology: we should look for continuous and discrete, and replace it with numeric and categorical. The term domain is also meaningless outside the 80s and 90s ML. Scheme is now a workflow.

  4. Style: remove all occurrences of "you", "your" etc., like in *Select the variables you wish to see plotted. Optimize your projection with *, which should be "Select the variables to plot. Optimize the projection with ...". (This is mostly my fault, but I was half my age then...).

Image

janezd avatar Mar 15 '25 10:03 janezd

I agree the docs need improvement, especially for the screenshots and how the images are handled. The layout is fine for me, but a nicer design is always good. As for the writing/phrasing, I think we could run through the text on an LLM because they work quite well as autocorrect and would give a consistent style, then a quick read of a human could make sure that there are no idiotic mistakes.

borondics avatar Mar 15 '25 12:03 borondics