Misc. Documentation Notes

* Example, "covered in Chapter 1, Introducing Writer."
Should the name of another chapter be in italics or something? Or even hyperlinked? Actually, it should have a character style assigned.

* Similarly, in the Writer guide under "Finding and replacing text", names of UI elements are variously unmarked, italic, or bolded. Which should it be, under what conditions?
I consistently made sure they were bolded, or occasionally names of fields or tabs in italic. But, should buttons be bold and fields be italic? That is, the rules need to be nailed down. And, rather than just ad-hoc bolding, there should be a char style defined for that.

* I also note that the '→' character used in menu paths, set in "Liberation Mono" and bold, does not look good at all. The arrow head is too small, and it has thinner strokes than the text it is separating.

* We should share a project-specific dictionary with words like 'autocorrection' and 'autotext'. Having a dictionary, rather than just ignoring the wavies, will help ensure consistant terminology and spelling.

* I see the phrase "time-varying data" where the hyphen is shaded as if a field. But It's not telling me what this shading means. No tool-tip or interesting information when I right click. How do I find that?

* Note that choosing "default formatting" for a selection via the context menu does not save a Formatting change note! Somehow a whole bunch of copies of the word "options" were in a funny font.

* Example, "covered in Chapter 1, Introducing Writer." Should the
name of another chapter be in italics or something? Or even
hyperlinked? Actually, it should have a character style assigned.

+1

* Similarly, in the Writer guide under "Finding and replacing text",
names of UI elements are variously unmarked, italic, or bolded.
Which should it be, under what conditions? I consistently made sure
they were bolded, or occasionally names of fields or tabs in italic.
But, should buttons be bold and fields be italic? That is, the rules
need to be nailed down. And, rather than just ad-hoc bolding, there
should be a char style defined for that.

+1

* I also note that the '→' character used in menu paths, set in
"Liberation Mono" and bold, does not look good at all. The arrow
head is too small, and it has thinner strokes than the text it is
separating.

I'd prefer something like the ">" or "/" chars. Available in any font without any trouble.

* We should share a project-specific dictionary with words like
'autocorrection' and 'autotext'. Having a dictionary, rather than
just ignoring the wavies, will help ensure consistant terminology and
spelling.

+1

Very interesting notes, thanks.

John ... I guess if you are already doing this, so you could start it the
way you choose, later if we have a need to change it, we could always change
your template.

You already are working with building a template, so just keep on doing
that, and if it ever needs changing we change the template.

How about that?

Rogerio

I summarized what the template itself had to say about the use of styles (see Terminology and Styles under "various") -- I noted where I thought new styles looked useful. But the response I got about trying to do this level of update was basically, "Let's get the documents out first, and clean up this kind of detail later." Is that still the case? I don't know if anybody else has looked at that document yet, it will need updating when we focus more on this type of issue.

* Example, "covered in Chapter 1, Introducing Writer."
Should the name of another chapter be in italics or something? Or even hyperlinked? Actually, it should have a character style assigned.

They cannot be hyperlinked until all the chapters are all put in one book.

* I also note that the '→' character used in menu paths, set in "Liberation Mono" and bold, does not look good at all. The arrow head is too small, and it has thinner strokes than the text it is separating.

I happen to think that it looks good. There was not a centered arrow in Liberation Sans, that's why I used the nearest one I could find, in Liberation Mono.

Ron

I'll peruse what is under "various", if that's where such notes can be found.

My two cents: If I'm proofing for any reason and notice such things, I'd like to be able to mark them. It doesn't mean it is necessary to be complete at this point or that such a mark has any effect in the output, but it will save having to look for them again later.

So simply having a style defined would be helpful. We can decide on exactly how it should look, and make sure they are all covered, later. Until then, set a subtle effect for draft work and no difference from normal text on final output, so user's won't see it.

I agree -- right now, they are generally either OOoEmphasis or OOoStrongEmphasis, but not consistently. The template itself covers it under Character Styles -- I just summarized in a table for easier reference. It might be a start. And I've done the same thing sometimes when I happened to notice that the readability was affected. It's just not something to get really serious about yet, apparently. Doing it right will certainly be time-consuming -- but there seem to be at least two of us who are champing at the bit to do it!