Re: Response to Studio-PM’s Tech. Reports

[Dave Hill]

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.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://www.riverbankcomputing.com/pipermail/eric/attachments/20200520/aaddbd12/attachment-0001.htm>