Re: Calc needs another review

[Keith N. McKenna]

Michele Petrovsky wrote:

Folks, I've finished my proofreading of the Getting Started guide (version
4.1, copyright 2022).

The project is so well done that I have little to suggest in the way of
improving it. But I did find three contexts in which it might be tweaked a
little.

1.

A glossary, especially of terms (e.g., from pages 11 and 12, odbc; jdbc,
GNU, kernel, and glibc; page 114: regular expression; page 158: Bezler
curves; page 185: database normalization) with which a lot of people might
be unfamiliar, would make *Getting Started* even more useful.


1.

Greater consistency in the presentation of internal links (for instance,
some Figures being shown in the text *before**,* rather than after, the
link to them – such as, on page 273, the reference to Figure 244, which
occurs *after* the Figure itself) would improve workability.


1.

Some more “colloquial” wording might also serve to make less skilled
users more comfortable. For instance, on page 94, what's shown as “provides
the oportunity” might be better expressed simply as “allows you to”.

I've got lots more individual items, but those are the basic contexts. Tell
me how you'd like to proceed.

And thanks again for the opportunity …



Michele;

Thank you for all your good work on your review of the Getting Started Guide

Is this Glossary intended to be included as part of the Back Matter of 
the full book, or as Francis addressed below in his reply as a 
stand-alone document that could be inclusive of the complete set of User 
Guides.


How we proceed in the long run depends on a number of factors. For the 
Glossary it depends on its ultimate use. If it is meant as a stand-alone 
document for one guide or as an integrated part of the book it would be 
handled one way, if as a stand-alone document for the entire set of 
guides it would be another way entirely. I will start  a [Discuss] 
thread so that all the members can give their opinions on the best way 
to do it.


For the consistency of Figure placement I agree with Francis that it 
would be best addressed in the Calc Guide as the placement has to be 
addressed in the chapter documents. The full book is simply the chapter 
docs merged into one doc along with any Front Matter and/or Back Matter 
if it is required.



For the more colloquial wording, that can start to be addressed as I 
work through the Writer Guide, and followed up in the rest of the guides 
as they are started.


If you could write up your suggestions and post them here all of the 
team members can have access to them.


Regards
Keith





-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Calc needs another review

[Keith N. McKenna]

Hello Francis, I will comment on your suggestion in-line
F Campos Costero wrote:

Hi Michele,
I think a standalone glossary could be very useful. There is a lot of
jargon and it would not be practical to give an adequate explanation of
terms within the flow of the text.I also suspect that there would be a lot
of overlap in the terms among the various guides, making a standalone
glossary more practical.

Although a stand-alone Glossary would be an excellent addition, remember 
we also publish the individual chapters. It may be helpful to have a 
glossary specific to each chapter. What do you think?



You make a good point about the location of figures. I'm inclined to make
those changes in the next guide to get a major revision, which would be the
Calc Guide. I think Keith is about ready to publish the Writer Guide.



Actually I am not ready to publish it, With all the time spent on 
getting to Getting started book right, as well as things in my personal 
life, I am behind on reviewing the chapters. Chapter one is ready, but 
in Chpater 2 I found a number of corrections that need to be made. I 
will be starting Chapter 3 today and spending most of my time the next 
few weeks reviewing the rest of the chapters.



You are right about some passages being less friendly than they could be.
All of the guides suffer from uneven tone. There have been many authors and
I think some spoke English as a second language.It's probably not
practical, or even desirable, to completely even out the style, but
introducing a bias towards less formal writing is a good idea.



I wholeheartedly agree with the above. Some of it could also be from 
repeated us of the same phrasing or word. This is more a style issue and 
would need to be addressed on an individual basis. Some of these style 
issues may be a result of my own bias, for which I apologize profusely.



What would you think of working with me to complete the revision of the
Calc guide? The version in the Git repository has been substantially
revised from the version on the web page but it could use improvements like
the ones you suggest. In relatively little time we could have something to
replace the very old version on the web page. I think  that would bring the
biggest improvement to the published documentation for the least effort on
our part. We could then come back to implement your specific suggestions
for the Getting Started guide having acquired some experience on the Calc
guide.

I think this would a good idea as well. It would give Michele an 
opportunity to get familiar with GitHub and be able to more 
interactively rather than having to wait wait until a guide or it's 
chapters are published to he mwiki.


Regards
Keith


Thanks for all your effort so far. If you would rather concentrate on the
glossary exclusively or work on any other aspect of the documentation, just
say so!


Regards,
Francis

On Sat, Jun 10, 2023 at 12:34 PM Michele Petrovsky <
petrovskymich...@gmail.com> wrote:


Folks, I've finished my proofreading of the Getting Started guide (version
4.1, copyright 2022).

The project is so well done that I have little to suggest in the way of
improving it. But I did find three contexts in which it might be tweaked a
little.

1.

A glossary, especially of terms (e.g., from pages 11 and 12, odbc; jdbc,
GNU, kernel, and glibc; page 114: regular expression; page 158: Bezler
curves; page 185: database normalization) with which a lot of people
might
be unfamiliar, would make *Getting Started* even more useful.


1.

Greater consistency in the presentation of internal links (for instance,
some Figures being shown in the text *before**,* rather than after, the
link to them – such as, on page 273, the reference to Figure 244, which
occurs *after* the Figure itself) would improve workability.


1.

Some more “colloquial” wording might also serve to make less skilled
users more comfortable. For instance, on page 94, what's shown as
“provides
the oportunity” might be better expressed simply as “allows you to”.

I've got lots more individual items, but those are the basic contexts. Tell
me how you'd like to proceed.

And thanks again for the opportunity …


On Tue, Jun 6, 2023 at 12:57 AM F Campos Costero 
wrote:


On Thu, May 4, 2023 at 8:40 AM Keith N. McKenna <

keith.mcke...@comcast.net



wrote:


F Campos Costero wrote:

On the Calc Guide, I will first accept or reject all of the changes
currently shown and push those versions back to the repository.

Judging

from the first chapter, all of my and Dick's changes have not yet

been

accepted. I hope I will have time after that to do a full review of

each

document. Let me know if that plan isn't good.
Regards,
Francis


That sounds good Francis. Thanks for moving this along.

Keith


On Tue, May 2, 2023 at 9:08 AM Keith N. McKenna <

keith.mcke...@comcast.net>

wrote:


F Campos Costero wrote:

I'll take a look at the Calc changes.
Francis



Tha