It hasn't been indifference that has kept me from responding. 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. In that light, I wasn't inclined to provide a critique
despite having professional experience in preparating technical
documenation.
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.
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.
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. There
are some real gems in it: the application window layout model, tips
about efficiencies, and so on.
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.
Right off the top is the title. Is the document a Technical Report or a
User's Guide? 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.
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.
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
using Eric to create those same menu entries in their own applications.
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:
Introduction
- 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.
Quick Start
- an abbreviated guide for experienced IDE users
Tour of Eric
- pulling the various window snapshots and diagrams in the Report
together with brief explanations
Installation and Configuration
- extending the instructions on the Eric Installation page,
particularly with regard to often-used Settings
- for Linux, Windows and MacOS
"Hello World"
- or something slightly more complex, but text-based
-keep the exercise really brief - quick run-down for new users on
basic Eric workflow - e.g. entering code, running it, basic
debugging etc
Adding a GUI interface
- perhaps update one of the Tutorials
Plugins
Projects
More detailed chapters on the Eric interface.
FAQs
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.
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.
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. Put those comments in the Forward or in a discrete
section (or in a blog). They detract from the main text.
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.
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} section which seems to be a bundling together of various
bits of Forward, Essentials, 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.
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.
Similarly there are numerous cf., ref., [see], see command and others
which could very profitably be replaced with hyperlinks.
The Report would be well served by help from a strong editor. The
Report's use of English is flowery, idiosyncratic and repetitious.
For example:
"Compatibility with Python ver. 3 or/and 2
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.
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."
meaning, I think:
"Compatibility
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.
This Report is based on Python 3 and PyQt 5."
The Report then repeats the compatibility point at more length a few
pages later.
The Report invites feedback from Python 2 users? Would the Report change
because of that? It seems unlikely.
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.
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.
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".
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.
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.
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.
In {3.South} the Report provides a similar catalogue of possibilities in
the Interactive Shell, the Task Viewer, etc.
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.
In sum, I find the Report occasionally 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.
I hope my remarks will not be taken as deliberately harsh or as an
attack 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.
David
On 2020-05-20 8:10 a.m., Studio - PM wrote:
>when engaged in a ‘real’ development task.
Dear Mr. Edward Mansfield,
you represent precisely the intended reader of my Reports. I wrote
them for you, and for other Eric users like you.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 “‘real’ development
task”, 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.
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.
So, all the best. Yours,
- P.M.
