brainstorming about the LibreOffice docs team workflow

We can setup some automatic rules to rename files in Alfresco... so both
are possible, you all only need to agree on something :wink:

1) Yes. Although some would argue that, in the name of project
openness, all content stored on Alfresco should be visible. But the
answer to your question is that it's easy to use permissions only to
showcase stuff you consider to be published and world-ready.

2) I don't quite understand the question here. But understanding
versioning systems was confusing at first, for me. But, once one takes
the concepts on-board and uses them in association with file meta
data, it falls into place.

The only question is this: does one work more effectively with a
manual system that is intrinsically "less efficient" from a geeky
viewpoint but that is easier for non-geeks to understand and lets them
get work done today rather than in 2 months time after RTFM?

Again, it's a choice to be made.

That said, I appreciate that Alfresco is more convenient to use with
one unchanging file name for each version of LO. I can manually change
filenames upon download if that makes the whole process easier for
everyone.

It's not really a question of keeping one unchanging file name to suit
working with Alfresco. The advantage is that one would take advantage
of Alfresco's file versioning to:

a) avoid having to update download links on http://libreoffice.org and the wiki;

b) avoid the need to keep different files containing different
versions of the same document. The versioning system stores all the
different historical versions of that document, and you can get a
download link to each different past version of a file if you want to
offer-up documentation for different versions of LibreOffice.

You can easily live with one unchanging file name if you store the
changeable information (version of LibreOffice covered, etc.) in the
doc's meta data rather than incorporating it in the filename.

I find this extremely convenient and simple. While I can go back to
Alfresco and download an older version of a file if I want it (or look
in the metadata to see when and by whom it was changed), in most cases
that is a nuisance compared to having it on my own computer with the
info in the filename.

I can understand that. It's a pity that there are no extensions to
file managers like Windows Explorer and Nautilus, etc., that allow
reading of ODF file meta data without having to load a program to do
so. There are various small, quick-loading utilities for reading MS
Office file meta data without much hassle, but I'm not aware of any
for LibreOffice and its ODF files.

I guess you'd need to make a choice here. Is using file meta data for
storing version-related information more convenient that using special
file naming that is quicker to read but entails a lot of manual
renaming and link updating?

If you were to use http://media.libreoffice.org as the download point
for documentation, then all the dates and other information could be
automatically extracted from the file's meta data, which would do away
with the need for manual updating of that information.

However, that would not work with http://libreoffice.org or the Docs
section of http://wiki.documentfoundation.org, as - AFAIK - they do
not incorporate the ability to extract and display document meta data.

Not so, in fact: the idea would be not to have different files but to
use the separate links that Alfresco would provide, that link to
different versions of the same file.

Hi :slight_smile:
I think Alfresco allows you to have
1.  folders where stuff is kept private so that you need to login to see the contents.  This is where almost all the work would be done (obviously)
2.  other folders which can be accessed by "the general public"

Presumably if there was 1 folder for guides for 3.3.x and another for 3.4.x then files in each of those could have the same name as each other and only the link's pathname would be different.

So. most people would only be aware of looking at "The Writer Guide" but techie people and "those in the know" might notice the extra info in the url or where-ever.

Regards from
Tom :slight_smile:

Hi :slight_smile:
That might save us a fair bit of awkwardness and potential inaccuracies.

At the moment the Publications wiki-page could hold maybe 1 more branch (the 3.6.x) and still be fairly easy to read on non-widescreen monitors (the old standard aspect ratio 4:3).  It's only really the latest guides that need to have precise dates.  Older guides just need a rough figure, even just the year is precise enough for the older guides.

However people have already been talking about tidying the page up or moving to a completely different way of presenting the information.  I think Alfresco would make it more presentable.

Regards from
Tom :slight_smile:

Hi,

On 23.08.2012 15:10, David Nelson wrote (in doc list):

... It's a pity that there are no extensions to
file managers like Windows Explorer and Nautilus, etc., that allow
reading of ODF file meta data without having to load a program to do
so. There are various small, quick-loading utilities for reading MS
Office file meta data without much hassle, but I'm not aware of any
for LibreOffice and its ODF files.

Sure? Anybody knowing an odf meta data viewer? Does not KDE have a 'show meta
data' option (at least on mouseover)?

(if not - could that be a GSoC 2013 idea?)

Regards,
Nino

<Total snip>

      After reading some of threads that this has created, I must say that I am confused. It is very difficult for me to follow any of the trends of thoughts. Some of the terminology is unknown to me as well.
      From what I understand about Alfresco, the information could be better presented there in the Discussion section of a site. There the areas of discussion can be divided into separate topics. We can comment on one or more topics that others will see in context.
      At least this is how I think a Discussion section is suppose to work: brainstorming while collaborating with others.
      My problem with the emails in these threads is that they do not include all of the text of the previous email to which the person is responding.
      I'm going to try to take these threads apart and see if I can put them into some order so they make some sense.
      I can see advantages to using Alfresco if we are willing to learn how to use it, one small step at a time in the beginning. Later we can take bigger steps.

--Dan

Dan wrote:

<Total snip>

      After reading some of threads that this has created, I must say
that I am confused. It is very difficult for me to follow any of the
trends of thoughts. Some of the terminology is unknown to me as well.
      From what I understand about Alfresco, the information could be
better presented there in the Discussion section of a site. There the
areas of discussion can be divided into separate topics. We can comment
on one or more topics that others will see in context.
      At least this is how I think a Discussion section is suppose to
work: brainstorming while collaborating with others.
      My problem with the emails in these threads is that they do not
include all of the text of the previous email to which the person is
responding.
      I'm going to try to take these threads apart and see if I can put
them into some order so they make some sense.
      I can see advantages to using Alfresco if we are willing to learn
how to use it, one small step at a time in the beginning. Later we can
take bigger steps.

--Dan

     I have created a ODT file with the comments from this topic in our mailing list. It is available at:
http://alfresco.libreoffice.org/share/page/site/alfrescoBrainstorming/document-details?nodeRef=workspace://SpacesStore/31a00fb0-a2d5-4ee3-ac02-102cbb4956dd
      Unfortunately, when you click on this link, this takes you to the login page. So, you must first be a member of Alfresco...
      I placed all of the comments following the paragraphs to which they apply. I also included the name of the person making the comments. Perhaps this will make this thread more understandable.

--Dan

IMO, a system that is easy for newbies and non-geeks to understand and
get work done is MUCH to be preferred.

That said, I think we could have a compromise method of working that
includes both the geeky advantages of metadata and the non-geeky
advantages of different filenames for different LO versions.

--Jean

More questions. Still trying to grasp what Alfresco versioning can and
cannot do. Sorry if I'm thick, but I doubt I'm the only person reading
this thread that is confused or unclear on the topic.

You mean, not store the files on the wiki? But only on Alfresco, with links from the wiki?

Well, you can store the files on Alfresco, get public links to them
(not requiring a log-in) from http://media.libreoffice.org, and post
the links on http://libreofficeorg and the wiki (although on those 2
sites you can't display the meta data).

Or you can have http://media.libreoffice.org:8081 (the port number is
temporary, until its reconfigured to show on port 80) as your main
download point instead, showing all the document meta data and,
feasibly, a browsable preview of the document.

So I can get (horribly long and user-unfriendly) download links to
different versions of a document and post those links on wiki or
website or wherever. That still doesn't solve the problem of how
people know, ONCE THE FILE IS DOWNLOADED TO THEIR COMPUTER, what
version of LO it's for. I'm sure I'm not the only person who downloads
user guides and then (an hour or a day or a month later) can't easily
tell what software version they were were for.

What about people who want to go to, say, media.lo.org, browse around,
and find individual chapters or books for a specific version of LO?
(In other words, not following specific download links.) At the moment
it's clear (by the directory structure: different folders for
different LO versions) and the filenames. I don't understand how they
will be able to tell this information if there is only one "Published"
folder for each book, and one filename for each chapter.

My questions are not just about how we, the Docs team, can work
efficiently. Equally, or even more importantly, we need to consider
how our consumers, the users, can easily find, identify, download,
store and retrieve the docs they need.

Another reason why different filenames for different LO versions are
useful: when a user reports an error, they need to tell us which file
it's in (or, in your system, which version of that file), because we
need to know if it's an obsolete version or only applies to a specific
version, etc.

Also, I don't understand how, if all the versions of a file (both
drafts and published) are stored under one filename, we can tell which
are the published versions vs the drafts.

--Jean

Although that would be a good use of Alfresco's Discussion feature, it
would effectively cut me out of any discussion when I am working on
iPhone or iPad, without access to a computer. Unless, hmmm.... I must
test the iPhone/iPad app for Alfresco to see if it would do the job.
(Android version coming soon.)

The other problem with holding a discussion on Alfresco (as with any
forum or other web-based program) is that people would need to go to
the site to read and contribute, instead of having the discussion come
to them. So there are pros and cons to doing it that way. Unless,
hmmm... can individual Alfresco users choose to have notifications
emailed to them when something new is posted on a topic?

I see I need to do more research on what Alfresco (and the mobile
front-end) can do. In my non-existent spare time!

--Jean

Hi :slight_smile:
Just speculation but ...

I'm not convinced the ODFAuthors system is simpler.  It's just that more people are familiar with it and have been using it for longer.

However, it seems to be difficult to attract and retain new people and that may be an indication of complexities that longer-term users don't notice any more.

Ok, so i am not convinced the ODFAuthors system is more complex either as i have no evidence nor experience either way. 
Regards from
Tom :slight_smile:

Hi Jean,

More questions. Still trying to grasp what Alfresco versioning can and
cannot do. Sorry if I'm thick, but I doubt I'm the only person reading
this thread that is confused or unclear on the topic.

It also took me a while to get my head around versioning when I first
encountered CVS and SVN.

I guess one could think about it like this:

Imagine you've got a nice, friendly wooden table as a desktop. On it,
you've got an empty in-tray.

Now imagine you've got a robot who deals with serving you documents
from the in-box, and with putting them back in again after you've
written something on them.

You take a clean sheet of paper and write a note on it. At the top of
the document, you give it the title, "Notes". You're done with it, and
tell the robot to put it in the in-box. The robot does so, and puts a
post-it on the sheet of paper with a note that this is version 1 of
the document called "Notes".

10 minutes later, you want to add another note to the sheet of paper.
You tell the robot. The robot duplicates the document and puts the
duplicate copy on your desktop.

You write another note, and you're done. You tell the robot to store
the document back in the in-box. Obligingly, the robot takes the
duplicated document with your additional note, and stacks it back in
the in-box on top of the first sheet, putting a post-it on the new
copy saying that this is version 2 of the document called "Notes".

Later, you want to edit that note. You tell the robot to give you your
"Notes" document. The robot duplicates version 2 of the "Notes"
document (without putting any post-it on it) and puts it on your
desktop. You scribble out a couple of words and, over the top, you add
a couple of better words. You're done, and you tell the robot.

The robot takes the document, adds a post-it saying "Version 3", and
puts it on the stack, which is now 3 sheets high.

A few minutes later, you didn't like the change you made. Because the
robot is keeping versions, you could ask it for the last version it
filed away ("Version 3" on the post-it), or for the version before
that ("Version 2" on the post-it). In the end, you ask for "Version
2". The robot duplicates the document with the post-it marked "Version
2", and puts it on your desktop (without a post-it).

You make some changes and add a new note. You then tell the robot to
file the document away, and it does so: it adds a post-it "Version 4"
to the document, and adds it to the top of the stack.

You now have an in-box with a stack of 4 copies of the sheet of paper,
with each copy being a version of the document after retrieving it,
doing some work on it, and then re-filing it in the in-box.

That's a very simplistic way of looking at the basic process.

In the case of Alfresco, you can see the version number (i.e. the
version from the version control system's viewpoint) in the little
black label to the right of the document name in the repository
browser.

If you click on the document title or document thumbnail, you go to
that document's preview and details page. On that page, in the
right-hand column, you can see a list of the various versions of the
document, the name of the person that uploaded that version, and any
notes they left when they uploaded it.

When uploading versions of a document, it would be important for each
submitter to add at least brief notes about the current considered
status of the document and what work the person has done. That will
help other human beings keep track of the collaboration.

Also, updating the meta data in a document regularly after doing work
on it is another way of providing information about its current
status.

Alfresco will happily display that meta data on
http://media.libreoffice.org (as well as in the document's preview and
details page).

There are a couple of introductions to version control systems here:
- http://betterexplained.com/articles/a-visual-guide-to-version-control/
- http://guides.beanstalkapp.com/version-control/intro-to-version-control.html

I'll reply to your other questions in a separate post.

Hi Jean, Dan,

     From what I understand about Alfresco, the information could be better
presented there in the Discussion section of a site. There the areas of
discussion can be divided into separate topics. We can comment on one or
more topics that others will see in context.
     At least this is how I think a Discussion section is suppose to work:
brainstorming while collaborating with others.

Although that would be a good use of Alfresco's Discussion feature, it
would effectively cut me out of any discussion when I am working on
iPhone or iPad, without access to a computer. Unless, hmmm.... I must
test the iPhone/iPad app for Alfresco to see if it would do the job.
(Android version coming soon.)

I think that, at this stage, we could maybe store Dan's document in
the Docs section of the TDF wiki, perhaps on a new "Alfresco
brainstorming" page. I think tha it's useful to have a summary of the
discussions in this thread, but that Alfresco is not the best place to
store it at this stage, since some people are not at ease with it (a
LibreOffice Alfresco contributor's guide will be essential if Alfresco
is adopted as the team's working tool).

The other problem with holding a discussion on Alfresco (as with any
forum or other web-based program) is that people would need to go to
the site to read and contribute, instead of having the discussion come
to them. So there are pros and cons to doing it that way. Unless,
hmmm... can individual Alfresco users choose to have notifications
emailed to them when something new is posted on a topic?

Alfresco can easily be configured to send out email notifications when
events take place.

So I can get (horribly long and user-unfriendly) download links to
different versions of a document and post those links on wiki or
website or wherever. That still doesn't solve the problem of how
people know, ONCE THE FILE IS DOWNLOADED TO THEIR COMPUTER, what
version of LO it's for. I'm sure I'm not the only person who downloads
user guides and then (an hour or a day or a month later) can't easily
tell what software version they were were for.

Yes, the download links are hardly human-readable. This is certainly
something that advanced configuration of the Alfresco platform could
resolve, but - at present - one would have to live with this
limitation.

As regards user guide versions and software versions, I'm not sure
whether the average end user faces the issue of having multple
versions on the same machine. Don't *most people* just stay up to date
with the latest version? As long as they have quick access to that
latest version, and an easy means of getting access to an index of
past versions, isn't that perhaps enough?

What about people who want to go to, say, media.lo.org, browse around,
and find individual chapters or books for a specific version of LO?
(In other words, not following specific download links.) At the moment
it's clear (by the directory structure: different folders for
different LO versions) and the filenames. I don't understand how they
will be able to tell this information if there is only one "Published"
folder for each book, and one filename for each chapter.

If the guest is browsing directly on the Alfresco platform via
http://media.libreoffice.org, this problem could be solved fairly
easily through appropriate permissions configuration, so that the
anonymous guest gets only to see the Published folder, with whatever
content you want to be visible to them (you can achieve that
fine-grained control through document-specific permissions).

But, here again, proper information in documents' meta tags would let
people make an advised choice of what do download, and so maybe one
wouldn't need to constrain what content they see.

But there's nothing stopping us using the current folder structure,
and perhaps it's a good idea to stay with it since it's easier for
non-experts to comprehend.

My questions are not just about how we, the Docs team, can work
efficiently. Equally, or even more importantly, we need to consider
how our consumers, the users, can easily find, identify, download,
store and retrieve the docs they need.

I guess one has to decide whether you want to use
http://media.libreoffice.org as a browsing facility for guests, or
whether you want to use it as a source of publicly-accessible links to
be posted on http://libreoffice.org and/or the wiki.

In the former case, the advantage would be that you could avoid having
to do updating work on 3 sites when publishing a guide. You'd only
have to work directly on the Alfresco platform, and possibly set
visibility permissions on a per-folder or per-document basis.

Another reason why different filenames for different LO versions are
useful: when a user reports an error, they need to tell us which file
it's in (or, in your system, which version of that file), because we
need to know if it's an obsolete version or only applies to a specific
version, etc.

Displaying version info stored in a document's meta tags would enable
users to be able to refer to a particular version of a document.

Also, I don't understand how, if all the versions of a file (both
drafts and published) are stored under one filename, we can tell which
are the published versions vs the drafts.

Again, entering information in a document's meta tags would be the
solution. One just has to devise an appropriate set of meta tags.

Hi Dan,

I have created a ODT file with the comments from this topic in our mailing
list. It is available at:
http://alfresco.libreoffice.org/share/page/site/alfrescoBrainstorming/document-details?nodeRef=workspace://SpacesStore/31a00fb0-a2d5-4ee3-ac02-102cbb4956dd
     Unfortunately, when you click on this link, this takes you to the login
page. So, you must first be a member of Alfresco...
     I placed all of the comments following the paragraphs to which they
apply. I also included the name of the person making the comments. Perhaps
this will make this thread more understandable.

Thanks for that, I think it's really useful to have this. But, as I
commented in another post, I reckon the TDF wiki might be a better
place to store it at this stage, possibly on a newly-created "Alfresco
brainstorming" page.

Would that be something that you or, maybe, Tom might do? If not, I
might try to find time for it in the next week or 10 days, or when we
reach an appropriate point in the to-and-fro of questions and
answers...

Hi Dan,

    I have created a ODT file with the comments from this topic in our
mailing list. It is available at:
http://alfresco.libreoffice.org/share/page/site/alfrescoBrainstorming/document-details?nodeRef=workspace://SpacesStore/31a00fb0-a2d5-4ee3-ac02-102cbb4956dd
     Unfortunately, when you click on this link, this takes you to the login
page. So, you must first be a member of Alfresco...

If you take the link to the document from http://media.libreoffice.org
then it would be publicly-downloadable without requiring a login.

Hi Cedric,

We can setup some automatic rules to rename files in Alfresco... so both
are possible, you all only need to agree on something :wink:

Since you're an Alfresco consultant, please could you give us some of
your expertise and advice in respect of some of Jean's and the team's
other questions? Your POV would be valuable.