Re: Response to Studio-PM’s Tech. Reports
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 relev
Re: Response to Studio-PM’s Tech. Reports
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 Wi
Re: Response to Studio-PM’s Tech. Reports
> 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.
Re: Response to Studio-PM’s Tech. Reports
Hello Edward, this is a very valid statement. Unfortunately there haven't been many volunteers doing some kind of documentation for eric. As eric ist mostly run as a one-man show, I am not in a position to write descent documentation. However, maybe somebody on this list will read this post and step in like Pietro did years ago with his Technical Reports. Even though some parts are outdated, they are still valuable. That is the reason they are still available through the eric web site. Regards, Detlev PS: Yes, eric has probably much more to offer than you already discovered. Just ask what you are looking for and I will try to point you in the right direction. Am Mittwoch, 20. Mai 2020, 12:03:46 CEST schrieb Edward Mansfield: > As an Eric newbie and with the dearth of user documentation for eric I have > found the Tech Reports extremely useful. I really appreciate the effort > expended. Eric seems like a really good and powerful IDE with lots of > useful features. The major problem is lack of documentation. Experimenting > with all the features to figure out how they work is time consuming and > very distracting especially when engaged in a ‘real’ development task. As a > consequence I only use a fraction of the features, which work really well > as far as they go. I always have the feeling that Eric could be doing a lot > for me if I only knew how. > > Edward Mansfield -- Detlev Offenbach det...@die-offenbachs.de
Response to Studio-PM’s Tech. Reports
As an Eric newbie and with the dearth of user documentation for eric I have found the Tech Reports extremely useful. I really appreciate the effort expended. Eric seems like a really good and powerful IDE with lots of useful features. The major problem is lack of documentation. Experimenting with all the features to figure out how they work is time consuming and very distracting especially when engaged in a ‘real’ development task. As a consequence I only use a fraction of the features, which work really well as far as they go. I always have the feeling that Eric could be doing a lot for me if I only knew how. Edward Mansfield
