[docs] [issue19608] devguide needs pictures

[Ezio Melotti]

On Thu, Jul 10, 2014 at 3:39 PM, anatoly techtonik <techtonik at gmail.com> wrote:
> On Wed, Jul 9, 2014 at 2:58 PM, Ezio Melotti <ezio.melotti at gmail.com> wrote:
>> What does "some immediate intro picture at the top of front page
>> illustrating transformation of Python code through the toolchain to
>> machine execution instructions" mean exactly?
>> If you are talking about pictures that illustrate how a Python source
>> code is parsed and converted to bytecode it doesn't belong to the
>> front page of the devguide.
>
> Yes. This is what I have in mind. Do you have any objective arguments
> against this? Why are you so sure there is no place for it? Do you have
> the specific picture that I can apply and see that it really doesn't fit
> here, so I can adjust it or just say what is conceptually wrong and leave
> the work for people who are more proficient in this?
>

If this is the picture you want, when you reported the issue you
should have said that you find
https://docs.python.org/devguide/compiler.html#abstract unclear and
that you think a flow chart would make things clearer.  Adding a flow
chart on that page might be ok, but it definitely doesn't belong on
the frontpage.  The reason why it doesn't belong there is that 99% of
the people who starts contributing aren't there to hack on the
compiler (and if they are, they likely know already how it works), and
while having an idea of how it works is useful, there are things that
are much more important (e.g. where to find the code, how to use the
different tools, etc.).
The compiler page already has a quite clear list of 4 steps, and lying
them horizontal and wrap them into boxes connected by arrows is not
going to make it much clearer, so a similar proposal could still be
rejected.

> Do you think that coders can not draw pictures, and the reason for you
> to close this issue is because you think that neither me, nor you can
> draw one? Should all bugs that neither me nor you can fix be closed?
>

That's not the reason, the main reasons are that the report is/was
vague and that request seems to have an arguably marginal benefit (the
list is already clear, adding a drawing/image/flow chart won't change
much).
If you take a look at e.g.
https://issues.apache.org/bugwritinghelp.html you should see how any
bug report/RFE should have at least these two qualities:
 * Reproducible: we need to be able to see that there are unclear
parts in the devguide that will benefit from an image;
 * Specific: we need to know exactly where are these parts.
As that page says, if your report lacks these qualities (and your
does) it will be closed (as it happened).

>> If you are talking about using
>> configure/make to compile python, at the top of the front page there's
>> already the quick start, which is a simple bullet list with useful
>> links.  You could turn that to an image but it won't get much easier
>> to understand, and you won't be able to add links to the image.
>
> No.
>
>> Can you link to a specific section of the devguide that you think
>> should be converted to an image, and suggest what things should be in
>> the image (and/or propose an ASCII-art version of the image you are
>> suggesting)?
>
> Read the subject again. `devguide needs pictures` is an issue. It is
> about means that devguide is not attractive, not that there is not enough
> information.

Attractiveness is subjective.  I used the devguide several times,
alone and during sprints, and improved things that were not clear, but
never felt the need for drawings (not saying that they are useless,
just not essential).  The quick start on the front page was added
after a sprint because I noticed that people were having problems
finding all the right steps scattered through different pages.  I
don't think anyone read the compiler page during the sprints, and if
they did no one complained about the fact that it's difficult to
understand without images.

> Just that this information is hard to read.

Again, can you quote exactly the part(s) that are hard to read?

> I am the user, I report bug. You ask me to be a design guy and developer.

In open source people tend to scratch their own itches (more or less
indirectly).  Especially in the case of RFEs, unless you manage to
convince other people that they should scratch your itch, no one is
going to do it for you.
This means that either you do it, or you find someone to do it for
you, or you leave the issue languishing there forever.
Also note that it's different with bugs -- the set of bugs is limited
while the set of potential improvement is infinite.

> I am sure
> that there are professionals who are not only interested, but could do
> this professionally and much better than me - identify the place and
> illustrate the process.

I don't think that's the issue, I could have done the flowchart myself
but it's not clear to me what flowchart do you want and how would that
make things better than a bullet list.

> Closing bugs, because they are reported by users is bad indicator.

That's not the reason why it was closed.  I explained the reason above.

> Knowing that I possess the skills to draw and
> develop is not a reason to assume that I am not a user and can do this.
>
> The picture that absolutely needs to be present is an overview of what
> Python is from inside

This is still very vague.  Even if I had artistic skills I wouldn't
know what to do with this request (unless you wanted a piece of
abstract modern art (possibly involving snake entrails?)).

>, a concept, an art, sketch - anything that draws
> interest and is based on real things inside, not a lie and not a compete
> fantasy.

Above you only mentioned a flow chart to explain the steps from code
-> parsing -> ast -> control flow graph -> bytecode.  I'm going to
assume that here you are expanding/generalizing the issue to other
potential (but still undefined) places.
That said, I think the only form of "art" that might belong in the
devguide is either ASCII-art, or some sort of flow chart.
I'm not sure what kind of art you are requesting now.

> The correct approach for it is to organize an art competition.

Do you seriously think that spending time and money to make an art
competition to make flow charts is "the correct approach"?  Do you
think that artists will flock and compete to make the best flow chart
for the Python devguide?
Do you think that the resulting flow charts will be significantly
better than the current bullet lists, enough to justify all the
effort?
Even if you find some artist willing to spend their time improving
Python, I think it would be better to use their time to do something
like http://learnyouahaskell.com/introduction#about-this-tutorial,
which will reach a far wider audience and be more useful for the
Python ecosystem.

> I think that organization that specifically created to "promote, protect,
> and advance the Python programming language" should somehow
> jump in and say something about this.