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
det...@die-offenbachs.de
