<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=windows-1252">
</head>
<body>
<p><font face="Helvetica, Arial, sans-serif">It hasn't been
indifference that has kept me from responding. </font><font
face="Helvetica, Arial, sans-serif">I have hesitated to share
these thought despite your repeated requests for feedback
because I am more than a little critical of the Report. I think
people in general are far to willing to share negative
commentary, often quite rudely. Especially when substantial
effort has been expend and is shared in the spirit of
open-source (as here) criticism should be kept to a minimum. </font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">In that light, I wasn't inclined to provide
a critique despite having professional experience in
preparating technical documenation. </font></font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">However, the Report
seems to be something you are genuinely seeking feedback on and
your conclusions of inanity or uselessness are unwarranted. I
take it that you feel you have completed work on the Report. If
that were not the case, I would suggest you adopt a
work-shopping approach to future development. This involves
using virtual work-shops to gather comments, suggestions, and so
on regarding structure and content from potential users at the
outset and throughout rather than asking for feedback from them
on a close-to-final version. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">I've tried to use the
Report several times but have found it frustrating. Here are
some personal views and reactions to the Report and some
suggestions.<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">You've clearly put in a
lot of work to produce the Report and have provided it under a
Creative Commons licence so kudos for that. </font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">There are some real gems in it: the
application window layout model, </font></font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif"><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif">tips about
efficiencies, and so on.<br>
</font></font></font></font></p>
<p><br>
</p>
<p><font face="Helvetica, Arial, sans-serif">I'm not sure it's
revolutionary to write technical documentation with the end-user
in mind, but regardless, is the Report written from that
perspective? I would have to say it falls short of the goal in
some respects.</font><font face="Helvetica, Arial, sans-serif">
<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Right off the top is
the title. Is the document a Technical Report or a User's Guide?
</font><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">If your goal is indeed to write a
document that is useful to users, calling it "User's Guide"
or something similar would make your goal clear from the
outset. </font></font> </font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">If in fact it's a
Technical Report, then perhaps it is useful to include a
recitation of practically every command from the menu bar, as
the Report does in {1.North}. This catalogue style of
presentation has the attraction of being orderly and highly
predictable, but makes it very difficult to synthesize
information and use-cases for real-world tasks. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">As well, Eric6 users
are, by definition, people writing Python code. It's not helpful
to them to read that File, Save saves the current text to the
original file, or that File, Close closes the file. They are </font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif"> using Eric to </font>create those same
menu entries in their own applications. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Personally, I'm looking
for a different sort of User's Guide. In it I would hope to find
subject-oriented, workflow-oriented chapters, something like,
say: <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Introduction <br>
</font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- an overview of
what Eric is and what it can do in the most general terms,
expanding on the description on the Eric Home page. <br>
</font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif">Quick Start <br>
</font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- an abbreviated
guide for experienced IDE users<br>
</font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif">Tour of Eric <br>
</font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- pulling the various
window snapshots and diagrams in the Report </font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">together </font>with brief explanations<br>
</font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif">Installation and
Configuration <br>
</font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- extending the
instructions on the Eric Installation page, particularly with
regard to often-used Settings</font></p>
</blockquote>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- for Linux, Windows
and MacOS<br>
</font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif">"Hello World" <br>
</font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- or something
slightly more complex, but text-based<br>
</font></p>
</blockquote>
<blockquote>
<p>-<font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif"> keep the exercise
really brief - quick run-down for new users on basic Eric
workflow - e.g. entering code, running it, basic debugging
etc<br>
</font></font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">Adding a GUI interface<br>
</font></font></p>
<blockquote>
<p><font face="Helvetica, Arial, sans-serif">- perhaps update one
of the Tutorials<br>
</font></p>
</blockquote>
<p><font face="Helvetica, Arial, sans-serif">Plugins</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Projects</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">More detailed chapters
on the Eric interface.<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">FAQs</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">So, as you can see, the
User's Guide in my mind would be a collaborative effort,
probably on a wiki. The Report doesn't go that route - fair
enough. It's your work product. I've written the rest of this on
the basis that the Report will continue more or less in its
current form.</font><br>
</p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">In some spots the
Report adds helpful notes about things that Eric does
differently or where it includes extended functionality, things
that clearly come from experience with Eric.</font><br>
</p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">It's clear that your a
big fan of Eric (as am I). Nevertheless, I suggest leaving those
remarks out of the body of the Report. You also express your
views about things not directly relevant, like the python2
python3 situation. </font><font face="Helvetica, Arial,
sans-serif"><font face="Helvetica, Arial, sans-serif">Put those
comments in the Forward or in a discrete section (or in a
blog). They detract from</font> the main text. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">The format and layout
of the text make it somewhat difficult to read, the use of
Courier New in particular. It tends to de-emphasize some of the
most important information in the text like menu commands. There
are a number of special characters sprinkled throughout, such
as <!>, <?> and so on. I see the interpretation of
them on p. 280. I don't find them helpful or informative. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">The structure of the
Report as a whole is not apparent until page 13, where the
Application Window layout model is introduced. Prior to that is
the {0.Lead} </font><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif">section which seems to be
a bundling together of various bits of Forward, </font></font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif"><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif">Essentials, </font></font>Introduction,
Compatibility, Scope and so on. Much of this would be better
(again, just in my view) in appendices or the like. The
Essentials, for example, mostly aren't essential. <br>
</font></font></p>
<p><font face="Helvetica, Arial, sans-serif"> <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">A Table of Contents
more typically appears at the beginning of a work rather than
tucked away towards the end. In a pdf document, it often also
appears as hierarchical Contents in the Navigation panel with
hyperlinks to the subjects, sub-subjects etc. That does not
appear to be the case here (at least in the pdf viewer I use,
Okular). That is a significant drawback, requiring the reader to
navigate to p. 282, locate the relevant section, and then enter
the appropriate page number in the pdf viewer. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"> </font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Similarly there are
numerous cf., ref., [see], see command and others which could
very profitably be replaced with hyperlinks. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">The Report would be
well served by help from a strong editor. The Report's use of
English is </font><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif">flowery, </font>idiosyncratic
and repetitious. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">For example:</font></p>
<p><font face="Helvetica, Arial, sans-serif">"Compatibility with
Python ver. 3 or/and 2</font></p>
<p><font face="Helvetica, Arial, sans-serif">From the current ver.
6, this same Eric IDE is fully Python 3 or/and 2 compatible,
both considered as an executing program and as a developing
environment. Indeed this same unique Eric IDE can be used with
Python ver. 3 only, OR Python ver. 2 only, or Python ver. 3 AND
ver. 2, together. This way offering a unique environment
where to attenuate the inconveniences caused by
such odd incompatibility between these two consecutive Python
versions, and possibly easing the transition between them. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">That said, we
have here decided to adopt and use Python ver.
3—and the consequently related accessories, such as
primarily the related PyQt library—as the only base language for
this Report1, and that for manifest reasons of manageability.
Giving thus for granted that a fool-proof compatibility should
be experienced in case of adoption of Python ver. 2."<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">meaning, I think: <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">"Compatibility<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Eric 6 is compatible
with Python 2 and 3. Both versions may be installed at the same
time, which may be of some help to those migrating existing
version 2 work to version 3. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">This Report is based on
Python 3 and PyQt 5."<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">The Report then repeats the compatibility
point at more length a few pages later. <br>
</font></font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">The Report invites
feedback from Python 2 users? Would the Report change because of
that? It seems unlikely. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font> </p>
<p><font face="Helvetica, Arial, sans-serif">There are many sections
titled Remark or Viewpoint. Sometimes the remarks are helpful
details for Eric users - pointers , tips, shortcut keys - and
don't really need to be separately titled. Others are editorial
and unhelpful, like the comments about what "API" means. The
Report contends that API has a "universally known" meaning but
in the next paragraph acknowledges that some don't agree with
that view - so not quite so universally known then. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">The Application Window
layout model at p. 13 introduces the first section {1.North} but
the section then immediately reverts to screen-grabs and
explanations of things already familiar to all but the newest
Windows/Mac/Linux GUI user - unnecessary for Python/Qt
programmers/developers. <br>
</font></p>
<font face="Helvetica, Arial, sans-serif"><br>
</font>
<p><font face="Helvetica, Arial, sans-serif">The majority of the
remainder of the section is a listing of menu commands. If the
reader wants to know about a specific command, this can be of
some use. Too often though that's the problem: "where is this
set", or "what is the command to do this".</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">I didn't know, for
example, where the debugging error highlight colour was set.
Surely one might be forgiven for thinking it was perhaps in
Settings, Preferences, Debugger or Settings, Preferences,
Editor, Highlighting, or that it might be found by searching for
"error" or "debugger" or "highlight". It turns out to be called
Debugging Line Marker in Settings, Preferences, Editor, Styles.
<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">I don't mean to suggest
that the Report should go through every section of Settings,
Preferences, but some description of the more commonly used
sections would have been appreciated.<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">After the lengthy
recitation of menus in {1.North} the reader is then taken to the
somewhat more helpful {2.Central}, but again, the focus is not
on, say, a typical Eric workflow, but a series of screen-grabs
of various parts of the Editor window, then a catolgue of the
context menu for the Tab, and so on. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">In {3.South} the Report
provides a similar catalogue of possibilities in the Interactive
Shell, the Task Viewer, etc. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">Finally, {4.West}
contains potentially some of the most interesting sections as
this is where working with Qt comes to the fore. Again, though,
the catalogue of commands makes it hard to discern how it all
works together or what the workflow might be for adding GUI
elements. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">In sum, I find the
Report </font><font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif">occasionally </font>useful,
when I can text-search for a narrow subject or when I know
exactly what I'm looking for, but in the main, I find it
frustratingly complex and burdened by extraneous material. <br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">I hope my remarks will
not be taken as deliberately harsh </font><font
face="Helvetica, Arial, sans-serif"><font face="Helvetica,
Arial, sans-serif">or as an attack</font> on you personally. I
appreciate the effort you have so obviously put in and commend
you for attempting such an ambitious work. It's far more than I
would have taken on myself.<br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif"><br>
</font></p>
<p><font face="Helvetica, Arial, sans-serif">David<br>
</font></p>
<p><br>
</p>
<p><br>
</p>
<div class="moz-cite-prefix">On 2020-05-20 8:10 a.m., Studio - PM
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:SN6PR0102MB3485A9A680E66652B4CCA550EFB60@SN6PR0102MB3485.prod.exchangelabs.com">
<meta http-equiv="Content-Type" content="text/html;
charset=windows-1252">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
<div style="font-family: Calibri, Helvetica, sans-serif;
font-size: 12pt; color: rgb(0, 0, 0);">
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<font face="Courier New, monospace"><font size="2"><span
style="margin: 0px" lang="en-US">><span> </span></span><font
color="#201f1e">when engaged in a ‘real’ development
task.</font></font></font></p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<font face="Arial, sans-serif"><font size="2"><font
color="#201f1e"><span style="margin: 0px; font-size:
10pt">Dear Mr. Edward Mansfield,</span></font></font></font></p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<font color="#201f1e"><span style="margin: 0px; font-size:
10pt"></span><font face="Arial, sans-serif"><font size="2"><span
style="margin: 0px; font-size: 10pt"> you represent
precisely the intended reader of my Reports. I wrote
them for you, and for other Eric users like you.<span> </span></span></font><span
style="margin: 0px; font-size: 10pt">Then, to better
tailor my work to the vision of what Tech.Doc.s should
be, I'd have appreciated to know a little more about
your “</span><font color="#201f1e"><font face="Courier
New, monospace"><span style="margin: 0px; font-size:
10pt">‘real’ development task</span></font></font><font
color="#201f1e"><span style="margin: 0px; font-size:
10pt">”, so to model my documentation upon real needs
of real user, real people. That to the ‘real’ common
benefit both of the users' community and of the
related tool's producer.</span></font></font></font></p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<br>
</p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<font face="Arial, sans-serif"><font size="2"><font
color="#201f1e"><span style="margin: 0px; font-size:
10pt">That was the essence of my “revolutionary” way
of intending the role and purpose of Tech.Doc.s in a
High Tech environment. Vision frustrated by the
substantial indifference of the intended audience, and
by my consequent perception of uselessness, inanity,
of my efforts.</span></font></font></font></p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<br>
</p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif">
<font face="Arial, sans-serif"><font size="2"><font
color="#201f1e"><span style="margin: 0px; font-size:
10pt">So, all the best. Yours,</span></font></font></font></p>
<p style="margin-top: 0px; margin-bottom: 0cm; color: rgb(50,
49, 48); font-family: "Segoe UI", "Segoe UI Web
(West European)", "Segoe UI", -apple-system,
BlinkMacSystemFont, Roboto, "Helvetica Neue",
sans-serif" lang="en-US">
<span style="margin: 0px; font-size: 10pt"></span><font
face="Arial, sans-serif"><font size="2"><span style="margin:
0px; font-size: 10pt">- P.M. </span></font></font></p>
</div>
<div>
<div style="font-family: Calibri, Helvetica, sans-serif;
font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
</div>
</blockquote>
</body>
</html>