Updating user guides to LibO 3.4.2

Sorry my ignorance, but ... what exactly was the rationale of storing
the files in the wiki?

Couldn't you/we keep the files in Alfresco and just linking them from
the wiki? So the problem of identical filenames should be solvable.

2¢ from Nino

Hi Jean,

> AFAIK, unless the filenames are different between the 3.3.x and 3.4.x
> versions of a chapter, they cannot both be stored on the wiki. Whatever
> is the latest upload will overwrite the other.

... maybe we could just add
a summary differentiation, e.g. GS34-ChapterTitle.odt rather than
0101GS34-ChapterTitle.odt...

That's fine with me. I've been thinking about dropping the first 4
digits anyway.

What do you think about the general principle of preferring the meta
data as a medium of storing info rather than file names?

Sounds fine to me.

--Jean

For working, it's imho often easier to have all needed meta info in the
file name as you can quickly see whitch version you have downloaded.

For end users the file name should be kept as simple as possible but not
missing *important* info. If you really intend to offer a complete set
of new documents for each minor version step, the version info should go
into the file name.

If only major versions are to be fully reflected in the documentation,
there is no need to put version info into the file name (as there are
several years in between them). Minor versions should then be reflected
by e.g. in-chapter-icons ("available since LibO 3.4" or similar).

In my eyes, the latter seems more reasonable, but I'm not involved in
the (English) Doc team work.

Again, my 2¢

Nino

Hi :slight_smile:
I don't know about using meta names. Cutting names to things like
GS34-ChapterTitleinCamelCase.odt(/pdf) makes a lot of sense to me. If meta-tags
would be clearer then that sounds good.
Regards from
Tom :slight_smile:

Hi Jean,

> In preparation, we should archive the files for v3.3.x so we don't
> overwrite them with the updated files. Translators may wish to have
> access to these files, without them becoming a moving target.
>
> David, how do you think this is best done in Alfresco? A separate space
> under English Content > Documentation for V3.3.x with all the v3.3.x
> user guide content under that, or a space under each individual guide

See below...

> for v3.3.x (leaving the existing spaces for work in progress) -- for
> example, English Content > Documentation > Writer Guide > V3.3.x
> archives? I could make an argument for either solution.

So we'd have "English Content > Documentation > Writer Guide > V3.3.x"
and "English Content > Documentation > Writer Guide > V3.4.x"

Then we could move the Drafts, Proofread, Reviewed and Published
folders under "English Content > Documentation > Writer Guide" into
"English Content > Documentation > Writer Guide > V3.3.x", create
"English Content > Documentation > Writer Guide > V3.4.x" and
duplicate the Drafts, Proofread, Reviewed and Published folders there
for updating then.

I think that this would be the better solution from the viewpoint of
the groups and permissions we'll set up after discussing the details
on the list. Does that seem OK to you?

Why do we need to preserve the 4 subspaces for the archived docs? I
don't have any objection to doing so; just wondering about your reason.

If we did decide to do as described above, I guess it would be
rational to do it now before spawning the 3.4 docs. It would involve
renaming every doc and inserting meta data; I'm perfectly OK to take
part in that job or even do it all myself once/if we have agreed on
the meta data. I could manage in in a pre-announced and approved
one-day session, so that work does not get held up for other people.
But guys would have to check-in all checked-out docs beforehand, and
then check them out again after the process was finished.

Okay with me, as long as I'm not doing the work. :wink:

> While updating chapters, we also want to replace any remaining
> screenshots with ones to match the agreed theme or that still contain
> OOo-related info that was missed earlier.

So what do we decide in the end? Go with your XP silver theme? Use the
default theme from whatever distrib or OS the screenshooting person
uses? Are we agreed that Windows screenshots are OK subsequent to the
SC's kind-of pronunciation/recommendation about that? Or do we
recommend a particular theme that can be availed in Windows/Mac/*nix
versions? Or do we pragmatically accept whatever we can get from
contributors, making the "entry barrier" as low as possible?

I think the consensus was: recommend, but not require, the "Ubuntu
XP-Silver" theme. A similar-looking theme on other platforms is okay,
but over time we'd like to replace non-standard images with those from a
single platform/theme. I think this meets the "pragmatic" requirement
(with which I agree) but works towards a more professional-looking
result.

The word "pragmatically" sort-of suggests my own POV, but I'll go with
whatever decision you and the team arrive at (unless other team
members strongly and rapidly veto your recommendation, I think we
should adopt it and move on quickly).

> We also need to decide whether to go ahead with my proposed
> reorganisation of the Getting Started guide and the Writer Guide -- or
> perhaps with some subset of my proposal. Richard Holt is working on
> changes to Getting Started, but there was some difference of opinion
> about some of my suggestions on both that book and the Writer Guide, so
> I'm unclear whether we're all agreed on the way to move forward. I
> really don't want to see everyone sitting around waiting for a
> consensus.

My own POV would be to make that a low priority or prefer to press
ahead with new stuff. But I'll be guided by what you feel is best and
+1 whatever you recommend (which I reckon we should adopt unless there
is a strong veto by other team members).

Two items I suggested can be done fairly quickly (dropping the "Creating
Web Pages" chapter and the "Keyboard Shortcuts" appendix from Getting
Started), but other items would take more work and/or are controversial.
So at this point I think it's best to do only those two changes while
updating the factual info for v3.4.x. That's assuming, of course, that a
full set of files for 3.4.x is the way to go, instead of what Nino has
just mentioned, which I'll return to in another note.

Also, *not* split the Writer Guide, since that was controversial. Time
constraints may also mean not adding new chapters (that is, any that
need to be written) to the Writer Guide on this update cycle. Work on
them, yes; get them ready for the following update cycle. But don't hold
up the book to get them in.

--Jean

Hi :slight_smile:
I think that having them on the wiki makes it clearer and avoids scaring people
with redirects. The wiki site just got spammed on a few main pages today so i
think it helps to avoid being scary. Also it means we have the originals safely
out of reach?

I'm not sure if those are the reasons nor if they are good ones. Just my 2¢
too.
Regards from
Tom :slight_smile:

Hi :slight_smile:
I think there is a bit more time to really get into the work this time. There
is proper LibreOffice documentation covering almost all except the very latest
features. So, it's still a race but not so bad this time :slight_smile:

I don't think the "Keyboard Shortcuts" & "Creating Web-pages" should be
dropped. But that's because i think of the GS as a general overview of all the
apps and everything, rather than as a beginners guide. I was hoping the
keyboard-shortcuts would be expended to help Mac users.

Regards from
Tom :slight_smile:

Well, GS isn't a general overview of everything; a lot is missing, some
of which is IMO more important than those two chapters. But no one has
come forth to write about other things.

"Creating Web Pages" is IMO a total waste of space. It doesn't talk
about the sort of things that most people are likely to want to do (edit
web pages as well as create them). It just describes how to use a wizard
to export from the various components to create very crappy and
out-of-date HTML... not something I would want to encourage anyone to
do.

You might have a better case about retaining "Keyboard Shortcuts". If we
do keep it, yes it's probably worth having someone with a Mac add the
Mac info. Most of what's in the chapter is copied directly from the
Help, btw. Mac users see keyboard help for the Mac. I have a Mac, but
I'm not motivated to expand that chapter.

--Jean

I have been thinking about the pros and cons of a new doc set vs "new in
3.4" info in the same chapter, but I have not had time to read up on
just what has changed from 3.3.x to 3.4.x. Sometimes relatively minor
functional differences mean that fields are moved from one dialog box to
another, or the names of things change, or other changes are made that
are difficult to handle clearly in a single file. Other times, what you
suggest works well.

When I've had time to look at the changes, I'll have something less
vague to say on the subject.

--Jean

David would know, but I don't think that would work. At the moment you
need a login to get to files on Alfresco, so I would think a link from
the wiki would fail.

Also, the location of files on Alfresco occasionally changes, so the
links could get mucked up.

At this time we are not storing the PDFs on Alfresco, but that could
change.

There is some merit in not keeping two copies of the published chapters
(one on Alfresco and one on the wiki), so your suggestion could be
useful if it's technically feasible.

I think David has agreed to include some meta info in the filename, so
the "different names on the wiki" issue is taken care of... and those of
us who want that info for other reasons are, I hope, happy too.

--Jean

Hi :slight_smile:
I'm sure there is some confusion somewhere. The 3.3.x series is not "older" and
the 3.4.x "new". Both series are being developed alongside each other.

The next release of LO is due to be the
3.3.4 due out on Aug 17th give or take a day or 2. Then the
3.4.3 on Aug 31st and
3.4.4 on Oct 5th followed by
3.3.5 on Oct 19th.
Regards from
Tom :slight_smile:

Thanks for that clarification, Tom. I'm sure I once knew that but had
totally forgotten. That makes a lot of my recent assumptions and
thinking obsolete.

I need to re-think the arguments for one set of files (like Nino
suggested) or two -- not an archived set vs a live set, but separate
sets for the 3.3.x series and the 3.4.x series. And I see why we might
need two sets of Draft-Reviewed-Proofread-Published spaces...

My initial reaction is two sets of files, but that really increases the
need for reusable material (the majority of info that is the same for
both series)... done in a way that doesn't confuse the contributors. I
WILL dig up my notes on how to do this, as mentioned in an earlier
message to this list.

Further comments welcome. Might help me sort out my thinking... if it
doesn't further confuse me. <chuckles />

--Jean

Hi :slight_smile:
Lol, phew. I thought you were on a wrong track but wasn't completely sure.

The longer gaps between series 3.3.x releases (and it's generally better
stability) made me think it was stable branch and 3.4.x was development as
various other OpenSource projects do. But i think that's not the way the devs
see it.

Regards from
Tom :slight_smile:

Tom, that's definitively wrong.

The 3.3 codeline is definitvely "older" than the 3.4.

Code development happens from one minor version to the next. Inside of a
"minor version code line" there are only bugfixes, no feature
development.

The question is, how much and what exactly has changed between 3.3 and
3.4, and how these changes are reflected best in the documentation.

Nino

> > David,
> > I'll respond to the rest of your note later, but for now I want
> > to
> >
> > address just one item:
> > > > We can then copy those files into the Drafts spaces, update
> > > > them, and save them under different names -- to avoid
> > > > confusion and to enable us to put them on wiki along with
> > > > the 3.3.x files. For example, 0101GS34-ChapterTitle.odt
> > > > instead of
> > > > 0101GS3-ChapterTitle.odt.
> > >
> > > I'd love to get the versioning info out of the file name and
> > > into the document's meta data, so that - for instance -
> > > "0101GS34-ChapterTitle.odt" would become "ChapterTitle.odt" and
> > > that doc's meta data contains all the info we want to store
> > > about that doc.
> >
> > AFAIK, unless the filenames are different between the 3.3.x and
> > 3.4.x versions of a chapter, they cannot both be stored on the
> > wiki.
>
> Sorry my ignorance, but ... what exactly was the rationale of
> storing the files in the wiki?
>
> Couldn't you/we keep the files in Alfresco and just linking them
> from the wiki? So the problem of identical filenames should be
> solvable.

David would know, but I don't think that would work. At the moment
you need a login to get to files on Alfresco, so I would think a
link from the wiki would fail.

There should be a fixed (dedicated) location for externally visible
documents of course. Alfresco is a content management system, so I'm
sure it allows such a setup.

Also, the location of files on Alfresco occasionally changes, so the
links could get mucked up.

Of course it has to be made sure that the links work properly, but
that's true for all (external) links, that they have to be kept actual -
all the time. So the names have to be chosen carefully, and maybe some
kind of automated link check could be implemented.

At this time we are not storing the PDFs on Alfresco, but that could
change.

There is some merit in not keeping two copies of the published
chapters (one on Alfresco and one on the wiki), so your suggestion
could be useful if it's technically feasible.

Yes, avoiding duplication and allowing identical names for different
documents was the main reason for this suggestion. But however - it's
just a suggestion, which we have to consider the pros and cons of.

Nino

Hi :slight_smile:
But the 3.3.x series is still being worked on and new releases are due in it's
series?
Regards from
Tom :slight_smile:

It's only *bugfix* releases, no feature changes.

Therefore, such releases are irrelevant for documentation.

*Feature* changes are indicated in the second place (3.X), while
bugfixes happen thereafter in the third place for each code line
independantly (3.3.X or 3.4.X).

Nino

Hi :slight_smile:
Ok, whatever reason the 2 different branches are being developed alongside each
other, both are available to users and so both need documentation.

Early 3.3.x series releases claimed to have longer term support for about a year
so we need to keep documentation available for a year for that series.
Presumably that will occasionally need updating as bug-fixes might sort certain
things out or tweak things a bit.

Regards from
Tom :slight_smile:

... or we find mistakes in the docs themselves. But those changes will
be fairly trivial to make, in terms of effort.

Nino, thanks for your explanation. With your help, I think I'm getting
it figured out now. I've been reading the "new features and fixes" page
for v3.4.x and that has helped too.

--Jean

Hi,

David would know, but I don't think that would work. At the moment you
need a login to get to files on Alfresco, so I would think a link from
the wiki would fail.

media.libreoffice.org is well underway and should be ready "soon" but,
at the present time, Jean is correct.

Also, the location of files on Alfresco occasionally changes, so the
links could get mucked up.

Yes, the Alfresco platform is still very a work in progress, so maybe
we'd decide to change a few things.

At this time we are not storing the PDFs on Alfresco, but that could
change.

My 2 cents is that it would be a good idea to put the PDF files on
Alfresco, too.

There is some merit in not keeping two copies of the published chapters
(one on Alfresco and one on the wiki), so your suggestion could be
useful if it's technically feasible.

I'd say it's an idea that could be discussed again in the near future,
once we can reasonably say that development work on workflows for
alfresco.libreoffice.org, and on media.libreoffice.org as a public
front end for Alfresco, has reached 1.0-type completion. For the
moment, IMHO, it makes better sense to keep things as they are and use
the wiki as the final drop point.

I think David has agreed to include some meta info in the filename, so
the "different names on the wiki" issue is taken care of... and those of
us who want that info for other reasons are, I hope, happy too.

After talking with Jean, what I suggested was to keep some minimal
differentiation in the file names and to place a lot more information
in the document's meta info, including such stuff as subject tags,
author info maybe, and other content. But I'll write back to the list
with detailed proposals, so as to get agreement from the team before
actually changing anything.