Updating user guides to LibO 3.4.2

Now that we have almost finished producing the first set of user guides
(for LibO 3.3.x), it's time to start work on updates for 3.4.2, which
has just been released. This should not be such a big job, so we should
be able to get through it much more quickly than we did with the first
edition.

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
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.

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.

Then, when the 3.4.x files begin to be published, they should be made
available on the wiki as well as (not instead of) the 3.3.x files,
because many people may continue to use 3.3.x for some time and need
access to the 3.3 files.

Also in preparation, we need to go through the features list to see what
needs to be changed. Making a table of chapters and needed changes (on
the wiki) can be very helpful here.

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.

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.

What have I missed or forgotten?

--Jean

Hi :slight_smile:
"The 3.3.3 is the stable version with longer term support." This was originally
billed as "one year's support". The next release is due to be the 3.3.4 on Aug
17th
http://wiki.documentfoundation.org/ReleasePlan

I think we need to actively maintain 2 sets of documentation, one for each
series.

Personally i think it's a bit of a nightmare especially as it is unclear what
the difference is between the 2 series. If one was development branch and the
other was stable branch then it might make sense. As it is we have one branch
that is sometimes extremely unstable, like the 3.4.0 release, and sometimes
extremely (supposedly) stable like the 3.4.2. Meanwhile the 3.3.x series
continues to be a lot more predictably stable. I think it's unclear why there
are 2 series and what the aim&objectives are for each.

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?

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.
I remember we had a thread about this a few months ago, but we didn't
reach a final decision about it, although you mentioned a number of
items that should go in the meta data (I can dig that out when I get
time today or tomorrow).

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.

(Alfresco can happily display a document's meta data, so it's not a
problem of not being able to identify and distinguish between
documents and versions).

What are everyone's thoughts about that?

Then, when the 3.4.x files begin to be published, they should be made
available on the wiki as well as (not instead of) the 3.3.x files,
because many people may continue to use 3.3.x for some time and need
access to the 3.3 files.

Yes, I agree... many users might not upgrade to 3.4 for quite a while yet.

Also in preparation, we need to go through the features list to see what
needs to be changed. Making a table of chapters and needed changes (on
the wiki) can be very helpful here.

Yes, I guess so... Until such time as I get alfresco.libreoffice.org
and media.libreoffice.org sorted out, I probably would not play a
major part in that...

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?

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).

What have I missed or forgotten?

Nothing I can think of.

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. Whatever
is the latest upload will overwrite the other.

--Jean

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.

Ah... yes... I'd overlooked that. Hmmmm, well, maybe we could just add
a summary differentiation, e.g. GS34-ChapterTitle.odt rather than
0101GS34-ChapterTitle.odt, because the 0101 means nothing to me, and
there's a lot of useful, explicit information we could store in the
meta data... We could add tags to mark up the particular subjects that
get mention in a given document, for instance.

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

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