I got some free time today and tried to improve the HTML version of the technical reference doc (https://gmic.eu/reference.shtml). Of course, it does not solve all the problems, it is just small improvements.
I’m wondering…
Do you sometimes read this technical reference documentation ? Is is worth spending lot of time improving it ?
What do you think about the today’s improvements ?
What important things are missing from your point of view ?
Hmm, I do like how it’s a bit easier to read. One thing I’d like to see is the shortcut command right next to the big name equilavent. Something like d3d | display3d. That way, G’MIC scripter could be less likely to have a oversight. I don’t know what else I can see that would be need of a fix, it seem clearer for me, and more accessible.
I use it all of the time, esp. when helping people on the forum. I am glad that @David_Tschumperle has made the tweaks on things that I have pointed out in the past. Overall, I like the changes. Remarks:
– The highlighting of code is distracting. Makes it harder to follow the flow of the text. Perhaps reducing its contrast would alleviate the issue. Personally, I don’t want it.
– The highlighting is inconsistent, or has the appearance of inconsistency. Some code and / or parameters that one would expect to be highlighted aren’t.
– I don’t see the point of adding a border around the command names. Making them bold and looking the exact same as they are within the sample code would be sufficient.
– Same with the circle pluses. The original text is good enough.
– Really, the most important thing is accessibility. I may have hinted this before. The next step forward to be to make sure it fulfills accessibility guidelines for things like contrast, readability, legibility, and standard compliance so that assistive tools such as screen readers could parse the document.
As for the English, for the most part it is done very well. There are parts that require more of an explanation but other than that, it is quite excellent.
Ignore the comment about indice v index. That is just nitpicking. Changing it doesn’t change the meaning one bit. That said, its usage is low side:
I’m often frustrated with G’Mic because for most of the filters, there is no documentation aimed at users. I’d be willing to help with that - for example what sliders in each filter do what, so that people have an easier time using the filters.
But I would need to be able to contact either the filter’s author or someone that can look at the code and explain it to me.
I’m pretty good at translating tech speak to normal speak. But I would have a lot of followup questions to make sure I understood stuff from the technical side well enough to write up a quick “how to use” guide in plain language.
I could help with that. Perhaps add a few more tutorials.
This isn’t directly related to documentation but discoverability is sort of an issue too. E.g., I think the plugin searches only the titles of the filters but not the description part. That makes it hard to find certain filters and discover new ones.
Could it possible to add description on the G’MIC filters? I know in theory that you can, but I do not know if @David_Tschumperle would approve of edits except from the author themselves. Maybe a separate repository for that would be needed.
Also, it’s hard to get into the habit of doing that for one’s filter.
References to other web pages aren’t hotlinks, eg “pixelsort” references " Pixel Sorting - satyarth.me" but it’s not a hotlink so I have to copy-paste the address.
There is generally no description of what parameters do, or what values are permitted. For example, in “pixelsort”, what values are permitted for “sorting criterion”? Some kind of text, or does it have to be an image? What does “mask” do?
Sort_list also has a criterion, with default “i”, but what does “i” mean? What alternatives might I use?
I would prefer keywords instead of numbers for parameters. Eg “linear” or “lanczos” instead of “3” or “6”. This would help me to understand commands like “+resize[-1] 120%,120%,1,3,0,1,0.5,0.5”, which I find cryptic.
Indeed, the docs can be daunting. Case in point: the number of questions I asked when getting into G’MIC, so many that there are still questions left unanswered or unread.
Hi,
documentation is a costly thing. Still trials to get an overview are sometimes helpful!
What about some sort of matrix similar to the beginning of http://www.aljacom.com/~gmic/commandes_gmic.pdf ?
An index is quite long …
That is also missing yes. Here I was speaking about the Technical reference documentation, which is for me the base documentation we should at least have
Personally, I’m not using the plug-in very often, and I’m not sure I’d be the best person to write a doc about it. If people are interested to do so, then I guess the wiki pages of the gmic-community repo (Home · GreycLab/gmic-community Wiki · GitHub) could be the best location fot that kind of documentation.
That is fixed, I’ve replaced all url by HTML links.
Just here to let the OP know that I actually prefer highlighting. For me, it’s a quick and easy way to see information I need if I’m looking to make a new filter. I know others might hate it because that it looks distracting, and I completely get that as the style isn’t consistent in a way. Can there be at least a option to enable highlighting?
Currently, as things are formatted, I agree that no highlighting is actually worse. I don’t have the old version but I think it has to do with the fact that the font is thinner and lighter. As said,
Try using http://wave.webaim.org/ to evaluate your web page. I haven’t tried it before and when I have just now it stalls my browser. Maybe I have a plugin that is blocking it…
About highlighting, the way I have just back ticked the web address, http://wave.webaim.org/, looks good to me. Perhaps, you could use a similar style.
I’ve make the code highlighting a bit more contrasted.
On the github issue (Bad English in the docs · Issue #107 · dtschump/gmic · GitHub), the OP suggests to replace the term list used everywhere in the doc by stack. It’s not really clear to me if that is a good idea or not. in algorithmics, a stack is a particular data structure which does not correspond to the G’MIC list of image (see Stack (abstract data type) - Wikipedia), because in G’MIC you can access to each elements individually, change their position and so on…
