Alfresco documentation: brainstorming about the LibreOffice docs team workflow

Hi Jean, I'll reply to you mail by mail...

David, I see you have provided the Enterprise edition of two of the
Alfresco manuals. Aren't we using the Community Edition of Alfresco?
Are there differences? Or perhaps Alfresco has not updated the
Community Edition manuals?

We are indeed using Community. There are differences between them, but
not really visible/pertinent at the level we're using it. The
documentation is usable for both. I don't think they actually maintain
2 sets - too much workload...

Hi Jean,

BTW, this wiki page includes a diagram of the workflow used by
ODFAuthors for many years for docs production. The descriptive text is
a bit out of date (especially info on naming convention) and not
relevant to Alfresco (again, naming convention), but the general flow
is one I think should be adapted to work with the Alfresco tools.
https://wiki.documentfoundation.org/Documentation/Development#First_steps_with_the_Documentation_team

OK, the workflow we originally set-up on Alfresco is a bit like Snakes
& Ladders. The doc start in the "Drafts" folder. A considered-ready
draft gets approved and goes forward to the "Review" folder. A
reviewer proofreads it, and either it gets approved and gets moved
forward to the "Publish" folder, or it gets rejected and goes back to
"Drafts". The act of approval or rejection (it wasn't always actually
used) was to click on one of two menu options in the right-hand menu
that appears when your mouse pointer hovers over the document. The
result was that Alfresco would move the document to one folder or the
other.

When the doc actually lands in the Publish folder, the bells sound and
the doc gets published.

This is a manual process in which a team member downloads the document
from Alfresco, generates a PDF from it, has to log into the wiki,
upload the documents, edit/update the links in the wiki page with the
published documents list
(http://wiki.documentfoundation.org/Documentation/Publications). Then
the team member has to log into libreoffice.org and update the docs
download page (http://www.libreoffice.org/get-help/documentation/)
with the new links from the wiki.

Note: some of the tracking functionality is done within the document,
using LibreOffice's changes tracking and comments features. I have
missed out on the "Feedback" folder (insert additional snake/ladder).

Questions: Is there a real need for more than Draft/Review/Publish
folders? What is the real value of the Feedback folder? Could we
usefully just eliminate it and simplify things?

Question: The workflow described on the wiki involves 4 roles -
Writer, Reviewer, Editor, Publisher. Could we usefully simplify that
to Writer and Reviewer? Editor and Publisher could potentially be
eliminated, because of my file-naming suggestion below.

Suggestion: On Alfresco, you could usefully revise the file-naming
conventions. Keep the conventions as regards the title of the manual.
But remove the version info from the filename. Instead, decide what
fields you want to have in the meta data of each file, and store the
version info in there only. The advantages I'd see are discussed
below.

Suggestion/thoughts: I guess this is stating the obvious, but
ultimately the team needs to choose between the current ODFAuthors
tool and Alfresco. Having both described in
http://wiki.documentfoundation.org/Documentation/Publications
*probably* discourages a lot of potential contributors because of the
complexity of the functioning. IMHO, even the workflow on either tool
is *possibly* more complex than necessary. Either move to Alfresco
(hosted either on http://alfresco.libreoffice.org or on
http://odfauthors.org) or stay with the Plone tool? OK, irrelevant to
the current thread. Forget I said that... :wink:

Possible different solution

Hi Jean,

OK, the workflow we originally set-up on Alfresco is a bit like Snakes
& Ladders. The doc start in the "Drafts" folder. A considered-ready
draft gets approved and goes forward to the "Review" folder. A
reviewer proofreads it, and either it gets approved and gets moved
forward to the "Publish" folder, or it gets rejected and goes back to
"Drafts". The act of approval or rejection (it wasn't always actually
used) was to click on one of two menu options in the right-hand menu
that appears when your mouse pointer hovers over the document. The
result was that Alfresco would move the document to one folder or the
other.

Reviewing and proofreading are two very different activities. A
reviewer needs to be knowledgeable about the software being described,
so that he/she can check the accuracy of every statement made about it.
A proofreader is looking for quite different things: errors,
infelicities of style, bad cross-references, figures that don't show
what they're supposed to, etc. Logically this should be the last stage
before publication, when the reviewers have done all they want to. But
your work flow scheme doesn't allow for this.

Question: The workflow described on the wiki involves 4 roles -
Writer, Reviewer, Editor, Publisher. Could we usefully simplify that
to Writer and Reviewer? Editor and Publisher could potentially be
eliminated, because of my file-naming suggestion below.

You can't eliminate the editor for the reasons given above. Reviewers
aren't editors. The two jobs need different types of thinking.

Possible different solution

Have 2 folders for each manual: "Work-in-progress" and "Published".

All work gets done on the file in "Work-in-progress" and there is only
ever one file for each chapter of a manual in the "Work-in-progress"
folder.

Alfresco's versioning system updates the version number of the file
each time someone uploads some work done (via "Upload new version"
under "More..."). One can easily roll back to a previous version
number if necessary, or download an old version number if desired.

Each worker enters a comment in the Alfresco comment box when
uploading, stating the work done (and/or in a comment field in the
document meta data).

The same file is used even when work starts on updating a chapter to
take account of a new version of LibreOffice. In this case, the
LibreOffice version number is updated by a team member in the file's
meta data. You don't have to worry about incrementing any file version
number in the meta data, because Alfresco is handling the version
numbering.

So how will people know when something needs a review? Or a final
edit/proofreading? The traditional way was to put it in a specific
folder whose contents could be checked up on periodically. If you don't
do that, it would have to be done via the mailing list.

Hi Hazel,

So how will people know when something needs a review? Or a final
edit/proofreading? The traditional way was to put it in a specific
folder whose contents could be checked up on periodically. If you don't
do that, it would have to be done via the mailing list.

One possibility would be to use currently-unused Alfresco capabilities.

It is possible for a team leader to set tasks and allocate them to
certain people, for instance. The people concerned would be emailed,
or an email could be sent to the docs list. Also, anyone invited to
take on a task would see that task in one of the widgets (boxes) on
their Alfresco profile page.

It would also be possible to start a blog on the Alfresco site, which
the team leader could regularly update with info about needed work,
etc. This blog can be publicly accessible.

Obviously, instructions and info about this kind of functionality
would have to be written-up in the contributor's guide, but you could
already get an idea of the possibilities in the "getting started"
guide at:

http://media.libreoffice.org:8081/file/English/Community/Alfresco_Documentation/Getting_Started_with_Alfresco_Share_Collaboration_for_Enterprise.pdf

What do you think about that?

Hazel has covered some of the important points I would have made. I'll
get back with a more detailed reply next week, after discussion with
techwriting colleagues at the OpenHelp Conference this coming weekend.

At this point, I'll address only one point: published ODTs are
essential for translators, among others, and since an ODT is a
precursor to a PDF, publishing them as well takes only trivial effort.
Leaving the ODT link off the website might be reasonable (for end-user
consumption), but that is different from not publishing the ODT on the
wiki and making it available through the Alfresco media front-end.

--Jean

Hi Hazel, Jean, guys,

Reviewing and proofreading are two very different activities. A
reviewer needs to be knowledgeable about the software being described,
so that he/she can check the accuracy of every statement made about it.
A proofreader is looking for quite different things: errors,
infelicities of style, bad cross-references, figures that don't show
what they're supposed to, etc. Logically this should be the last stage
before publication, when the reviewers have done all they want to. But
your work flow scheme doesn't allow for this.

I understand what you mean. In a formal organization (a software
company or whatever), the workflow you're talking about would be very
important. But, in the LibreOffice docs team, the actual reality is
that we currently have a small number active contributors whose work
contributions frequently overlap between those formal roles. Also, the
types of role that those contributors assume also change fluidly. A
given person is often doing both the reviewing and proofreading at the
same time. The editor and publisher is frequently doing those jobs,
too. And the editor/publisher roles sometimes have to be taken on by
someone else if a team member or the team leader becomes temporarily
unavailable. We *really* have a fuzzy, fluid organization.

Also, the team has people with different degrees of technical
proficiency in docs development and publishing and of technical
familiarity with the IT tools being used. And there's a permanent goal
of lowering the knowledge entry barrier for newcomers as much as
possible, and of encouraging new people to get involved. Some
newcomers become long-term contributors, others contribute for a short
while - or even only for a particular guide. But we want to preserve
high quality in the content produced.

I think I'd recommend maximal simplicity. That will facilitate
learning to contribute, learning to administer/maintain, the writing
of documentation for all that, and the actual implementation work
itself.

It would be possible to configure a very strict and controlling
workflow in Alfresco, with specific permissions for each work role and
each folder, and quite a bit of automation (automated movement of docs
from one folder to another, automated alerts via email, automated task
attribution to specific user groups, etc.). Or else things could be
left quite fuzzy, with everyone having almost identical powers, and
things being done much more manually (basically the current
situation).

However, IMHO, it would be good to start using Alfresco's blogging
facilities, maybe it's wiki functionality, and it's automated email
alerts and RSS feeds.

You could also consider Twitter as a good channel for updates, both
automated and manual. Using Twitter would do away with the need to
sign-up for and follow a mailing list, and put you closer to potential
contributors from the huge Twitter membership.

Most of all, I'd definitely recommend revising the file naming
conventions and taking advantage of Alfresco's built-in versioning.

And I'd definitely recommend coming-up with a clearly-defined set of
meta data fields to be maintained in each file.

If we arrive at a clear and comprehensible specification, I could
possibly see with the Alfresco project whether they might handle the
implementation.

Anyway, this is all thinking for your consideration.

You could also consider Twitter as a good channel for updates, both
automated and manual. Using Twitter would do away with the need to
sign-up for and follow a mailing list, and put you closer to potential
contributors from the huge Twitter membership.

Well, I am definitely not signing up to Twitter or Facebook. I have
better things to to with my time.

Most of all, I'd definitely recommend revising the file naming
conventions and taking advantage of Alfresco's built-in versioning.

+1 to that.

Hi David, all,
[...]

We *really* have a fuzzy, fluid organization.

And we are proud of it. :wink:

[...]

However, IMHO, it would be good to start using Alfresco's blogging
facilities, maybe it's wiki functionality, and it's automated email
alerts and RSS feeds.

I like the idea of wiki functionality especially for translation. We on German doku team tried to translate the documentation by wiki: Having the original text in little bit by bit and translating and reviewing/discussing that. At the end someone put it to one piece, complement screenshots etc. and then get the document to reviewing as a whole.
It seems that these are more steps but then you can get much more contributors even for little pieces. So we got translating the "Getting started". Maybe this is also something for the "EasyHacks for documentation".

You could also consider Twitter as a good channel for updates, both
automated and manual. Using Twitter would do away with the need to
sign-up for and follow a mailing list, and put you closer to potential
contributors from the huge Twitter membership.

But if I don't twitter (as I do) I'm out of contribution. And so this way is against simple contribution.

Yes. I'm sure I said the file naming conventions would be changed.

Jean

I think the process we choose should allow for and encourage, but not require, the steps or roles of reviewer, proofreader, etc even if we skip some steps (as indeed we do) or one person does several steps. I'll write more when I'm not on the phone.

Jean

Hi :slight_smile:
I often find it easier to go through doing 1 process at a time and then go through again for the other mission.  An odd note or 2 jic i don't spot something i may have noticed while my attention drifted from the mission at hand.  I'm not sure if you folks find the same.  I guess it's different for different people.
Regards from
Tom :slight_smile:

Hi Hazel,

Well, I am definitely not signing up to Twitter or Facebook. I have
better things to to with my time.

Twitter would be just part of a panoply of means of communication -
more "output only". Alerts (about stuff published, resources updated,
etc.) could be echoed to Twitter, and to RSS feeds, and to mailing
list(s), and to a blog, and to emails to individual recipients
(subscription being optional and manageable), etc., so that everyone
can receive the information via the channel that suits them, and to
give us means of communicating with the public and publicizing the
project.

Hi Klaus-Jürgen,

I like the idea of wiki functionality especially for translation. We on
German doku team tried to translate the documentation by wiki: Having the
original text in little bit by bit and translating and reviewing/discussing
that. At the end someone put it to one piece, complement screenshots etc.
and then get the document to reviewing as a whole.
It seems that these are more steps but then you can get much more
contributors even for little pieces.

I'll look further into other ways in which we might exploit wikis. For
instance, I'm wondering what possible means of communication there
might be with the TDF wiki for carrying across updates... Of course,
one would want to think about the question of pointless duplication of
resources... I'll investigate further.

Hi Jean,

I think the process we choose should allow for and encourage, but not require, the steps or roles of reviewer, proofreader, etc even if we skip some steps (as indeed we do) or one person does several steps. I'll write more when I'm not on the phone.

It would be really nice if we can arrive at a document that is as
brief as possible but that provides a clear and fairly comprehensive
specification of what the team needs/wants. Once this thread has gone
a bit further, I'll put some results to Jeff Potts and try and get
some input from him about it - including about possibilities we might
have overlooked, etc.

I've IM'ed with Florian Effenberger and he's pretty sure that TDF
would be willing to provide a server if people preferred to have
Alfresco hosted on a TDF-owned resource. It might be something to
think about now, before/while implementing a work organization for the
team, although it will also be possible in the future, too. But I
don't mind continuing to operate it from my own server, which is a
dedicated machine and provides really good performances/response
times. Got any thoughts about this?

Much better to have it on a TDF server.

Jean

Please wait at least a week so I have time to respond in more detail. Also I may learn some useful suggestions this weekend at OpenHelp.

Jean

Hi Jean,

Much better to have it on a TDF server.

OK, I filed a request with the BoD.

Hi,

Much better to have it on a TDF server.

OK, I filed a request with the BoD.

I've just been on the BoD confcall, and discussed the provision of a
TDF server to host the Alfresco platform. While the BoD didn't want to
make it an official voting issue, it was agreed by all that there is,
in principle, no problem with TDF providing the needed infrastructure.

Basically, they'd like Florian and the infrastructure team to deal
with the matter.

The only question to be clearly resolved is: does the Documentation
team really want an Alfresco platform?

If the answer is yes and the only real sticking point is that you want
it hosted on a TDF server rather than a community member's server,
then there will be no problem. I've been assured off-list and by the
BoD that TDF will provide what's necessary and I, for one, am willing
to install, configure, customize and administer the platform for you.

If, on the other hand, the answer is no, you don't actually want to
use Alfresco and you prefer to stay with the ODFAuthors tool, then -
again - there is no problem and we can simply close the subject.

Since the Alfresco platform has been online and available to you since
January 2011, I'd humbly suggest that people have had enough
opportunity to evaluate it as a tool, and that they should by now be
in a position to voice a preference.

In any case, do you think I should simply close down the server I'm
currently operating for for the team, since apparently it is no longer
being used?

I don't use the Alfresco site at all. I'm just not clever enough to
understand it!

We've had the time to evaluate Alfresco, but not the incentive. I'm trying to catch up now.

Having the possibility of TDF hosting is a big plus for me, so thanks for chasing that.

One annoying thing to me is that I have not seen an easy and convenient way to link directly to a folder or a file in Alfresco, so I can send that link to, say, Hazel, and say "Here's a file that needs editing" or "The files are in this folder." If there is a way to link directly, please tell me.

More questions coming, I'm sure.

Jean