Response to Studio-PM’s Tech. Reports

[Detlev Offenbach]

Hello Dave,

I understand your post such, that you have experience in writing user 
documentation and have given useful criticism from that point of view. Now I 
would go one step further and would like to ask, if you would be willing to 
spent some time and effort and rewrite the 'Technical Report' as a 'User Guide' 
with a structure as suggested. 

Regards,
Detlev

Am Donnerstag, 21. Mai 2020, 03:11:17 CEST schrieb 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.

-- 
Detlev Offenbach
detlev at die-offenbachs.de