a tutorial for "new Imagick()" and constructors for the other types in the navigation bar about imagickdemos HOT 6 OPEN

@BeholdersEye Please write some words here, and I'll figure out where they should go.

from imagickdemos.

I am not confident enough in my understanding to write documentation, in fact I could likely stand to read more myself. It just seems like a possible oversight that (all?) methods except the constructors have examples on phpimagick.com. The comments here seem like good places to begin:

https://www.php.net/manual/en/imagick.construct.php

https://www.php.net/manual/en/imagickdraw.construct.php

The examples for other methods likely include most possible variations of the constructor but without documentation for the constructor it is difficult to be sure. If I want information on the ImagickDraw constructor I might click around until I find that the ImagickDraw.rotate() method includes an example of the constructor with no arguments, but how could I know that I have seen every constructor even after visiting and viewing every example?

from imagickdemos.

I am not confident enough in my understanding to write documentation, in fact I could likely stand to read more myself.

Do you think it's any different for me?

Imagick is a thin wrapper. There is magic exposed by ImageMagick that is available through Imagick....but I've never known about it.

If you want to help, do this:

• take the things you think are important on that page:
• give each of them a little heading, and re-write the words to have a more consistent 'tone'.
• put them in a comment here and I'll add the Imagick::__construct page.

but how could I know that I have seen every constructor even after visiting and viewing every example?

You're looking at the wrong way; documentation is additive. Every piece of info added can add value. Yeah arranging it neatly take a bit of thought but you don't need to produce a completely complete article, just more stuff to add.

For the record, I never knew about the "ico:filename" trick before you told me there was useful info on that page.

from imagickdemos.

You're looking at the wrong way; documentation is additive. Every piece of info added can add value.

I fundamentally disagree with that. Less is more. Good documentation should treat the needle, not the hay, which is one reason writing it is so difficult. That cognitive burden can't be eliminated but it can be shifted from the writer to the reader by taking an "everything and the kitchen sink" approach. It can be, but I hasten to add, it should not be.

As an example: I don't dislike lorikeets by any means but most of the tutorials could probably convey their intention more clearly by inlining an image of the BBC's Test Card F or similar. That prevents problems with images failing to load (as the "logo" option currently does on the examples I checked). It is true that loading images from files is information added to the documentation but I don't consider its inclusion to add value unless the documentation is directly related to loading images from files. For example, the documentation for the imagick constructor(s) that load(s) an image from a file.

There is also the chicken and the egg problem of good documentation requiring such a thorough understanding of Imagick and ImageMagick internals that anyone capable of writing it would be unlikely to need it themselves. Case in point: If I possessed knowledge of all the imagick object constructors, as documenting them requires, I would have little interest in their documentation.

On that note, I found an authoritative source for information on ImageMagick's image constructor:

https://imagemagick.org/api/Image.php#Constructors

I made an attempt to format them for readability but the table-based layout used to contain the information is not human readable and also frustrates attempts to copy and paste them. (Pop quiz: How many signatures are listed in that table? How many descriptions? Is that your final answer?) Hard to navigate this bottomless pit with glazed-over eyes. Maybe that is why the Imagick constructors lack documentation. If so I can hardly blame you.

from imagickdemos.

On that note, I found an authoritative source for information on ImageMagick's image constructor:

Imagick goes through the 'Magick wand' api. Your link was a different api. So MagickReadImage would probably be it.

But even then some magic happens with 'special strings', and that knowledge is hard to find.

but most of the tutorials could probably convey their intention more clearly by inlining an image of the BBC's Test Card F or similar.

I'll think about adding a copyright free image like that.

That prevents problems with images failing to load (as the "logo" option currently does on the examples I checked

That was just me forgetting to commit the file.

There is also the chicken and the egg problem of good documentation requiring

No. The bigger problem is even when users are told explicitly how they can help e.g.

If you want to help, do this:

• take the things you think are important on that page:
• give each of them a little heading, and re-write the words to have a more consistent 'tone'.
• put them in a comment here and I'll add the Imagick::__construct page

For whatever reason people just don't contribute.

They'll sometimes take the time to suggest how stuff could be improved but actually spending time doing boring stuff, even when it's as simple as "take those words, rewrite them to be coherent, and post them here" seems to be something that users just aren't willing to do.

from imagickdemos.

No. The bigger problem is even when users are told explicitly how they can help e.g.

By the same token well-intended suggestions for improvement are oft-times met with a reply to the effect of "No, the real improvement would be x. You should get on that."

The omission of documentation for the objects' constructors seems like an oversight. If the omission is deliberate by all means carry on and don't mind me. On the other hand, if the omission was not intended, then expecting the person who observed and reported the oversight to also correct it seems optimistic to say the least.

from imagickdemos.