Bug 31956 - Improve wording for Readme packaged with LibreOffice 3.3 Linux downloads
Summary: Improve wording for Readme packaged with LibreOffice 3.3 Linux downloads
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
3.3.0 Beta3
Hardware: All Linux (All)
: high major
Assignee: Thorsten Behrens (CIB)
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2010-11-28 02:36 UTC by David Nelson
Modified: 2013-11-14 22:44 UTC (History)
6 users (show)

See Also:
Crash report or crash signature:


Attachments
Original version of the readme, without subsequent edits in progress to take account of Carl Symons' comments (39.38 KB, application/vnd.oasis.opendocument.text)
2010-11-29 03:06 UTC, David Nelson
Details
Updated readme for Linux downloads with fairly comprehensive installation instructions (22.09 KB, application/vnd.oasis.opendocument.text)
2010-11-29 09:42 UTC, David Nelson
Details
Raw readme file (17.97 KB, text/plain)
2010-11-30 13:55 UTC, Thorsten Behrens (CIB)
Details
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives (22.09 KB, application/vnd.oasis.opendocument.text)
2010-12-01 02:22 UTC, David Nelson
Details
This is the actual .txt readme that should be included in the .tar.gz (25.95 KB, text/plain)
2010-12-01 02:25 UTC, David Nelson
Details
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives (21.84 KB, application/vnd.oasis.opendocument.text)
2010-12-01 03:30 UTC, David Nelson
Details
This is the actual .txt readme that should be included in the .tar.gz/.zip download (25.67 KB, text/plain)
2010-12-01 03:31 UTC, David Nelson
Details
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives (21.41 KB, application/vnd.oasis.opendocument.text)
2010-12-01 11:52 UTC, David Nelson
Details
This is the actual .txt readme that should be included in the .tar.gz/.zip download (24.50 KB, text/plain)
2010-12-01 11:54 UTC, David Nelson
Details
Updated raw readme.xrm (26.34 KB, text/plain)
2010-12-01 16:02 UTC, Thorsten Behrens (CIB)
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Nelson 2010-11-28 02:36:02 UTC
Hi,

The readme packaged with the LibreOffice 3.3 Linux downloads contains no installation instructions.

I've attached herewith an amended readme that contains:

- instructions for installing LibreOffice on Debian/Ubuntu, Fedora, Suse and Mandriva, with supporting noteas for other Linux distribs;

- instructions for installing language packs on all the above distribs;

- instructions for de-installing an existing LibreOffice installation, covering all the above Linux distribs.

It would be useful to proofread what I've added, for technical correctness and accuracy.

Please can you include this with the next release?

Thanks if so. ;-)
Comment 1 carlsymons 2010-11-28 09:36:36 UTC
from ReadMe ...contents have been decompressed into a directory called "en-US"

For me, the tar file decompressed to: 
LibO_3.3.0beta3_20101115_Linux_x86-64_install-deb_en-US
Comment 2 carlsymons 2010-11-28 10:00:46 UTC
Readme "Launch the Synaptic Package Manager."

This package manager is not installed by default in recent versions of Kubuntu. The default package manager for Kubuntu is KPackageKit. For some reason, "LibreOffice" does not appear in the installed package list, and a search for this application returns no results.

Synaptic Package Manager, Muon Package Manager, and sudo dpkg --get-selections all show "LibreOffice3".

In Kubuntu, both Synaptic and Muon PMs would require an additional non-trivial installation step.

Recommend: LibreOffice de-installation with Terminal. Someone who is more knowledgeable of libreoffice and dpkg remove or purge would be better suited to developing these instructions.

The user is already recommended to use Terminal > locate libreoffice | less with manual deletions. Is it possible to use dpkg to accomplish the entire de-installation?
Comment 3 David Nelson 2010-11-28 18:39:58 UTC
Hi Carl,

Sorry, I didn't have time to draft instructions specifically for Kubuntu. Additionally, Ubuntu ships Gnome as its primary GUI. Plus Synaptic ships with Debian, Ubuntu and Fedora, and is therefore a component that is common to at least those three distribs. (I'm unable to confirm that for Suse, Mandriva, etc, but maybe it is too?)

If you prefer inexperienced users to do in all via the CLI, could you maybe draft me the command sequence necessary to do the job? Then I'm willing to re-write the instructions.

Or please feel free to make the edits you consider necessary...

However, my instructions *do* work, and no-one else appears to have thought to include some installation instructions with the Linux downloads. 

But the bottom line is that there have been a number of distressed users writing to the mailing lists pleading for some installation instructions... THEY need help...

I will review my draft again for any errors, but I was hoping that you guys might give me a little help...
Comment 4 carlsymons 2010-11-28 20:31:28 UTC
(In reply to comment #3)
> Hi Carl,
> 
> Sorry, I didn't have time to draft instructions specifically for Kubuntu.
> Additionally, Ubuntu ships Gnome as its primary GUI. Plus Synaptic ships with
> Debian, Ubuntu and Fedora, and is therefore a component that is common to at
> least those three distribs. (I'm unable to confirm that for Suse, Mandriva,
> etc, but maybe it is too?)

I agree that Synaptic is the way to go. But it isn't a standard feature for Kubuntu. And the standard package manager fails for me; searching for LibreOffice yields nothing. Installing a good PM just to de-install LibreOffice doesn't make sense to me.

> 
> If you prefer inexperienced users to do in all via the CLI, could you maybe
> draft me the command sequence necessary to do the job? Then I'm willing to
> re-write the instructions.

Here's where I'm in over my head. I don't know if dpkg -r or dpkg -p can be run with a wildcard * such as is used to do the install. From the poking around I've done, I'm guessing not. And I feel squeamish experimenting with it. It looks like CLI uninstall could turn into a bigger hassle than just installing Synaptic. Installing Muon entails adding a PPA repository, not necessarily something that a lot of people do.

> 
> Or please feel free to make the edits you consider necessary...
> 
> However, my instructions *do* work, and no-one else appears to have thought to
> include some installation instructions with the Linux downloads. 
> 
> But the bottom line is that there have been a number of distressed users
> writing to the mailing lists pleading for some installation instructions...
> THEY need help...
> 
> I will review my draft again for any errors, but I was hoping that you guys
> might give me a little help...

I'm happy with what you've written outside of the different file name, and this business about de-installing with Kubuntu.

I think that you are absolutely correct about getting instructions out. The skill level required to operate LibreOffice is much different from sudo, dpkg, cd, etc. And decent instructions are needed for the not-so-technical; I'd guess most users will be in this category. We need to keep in mind that we are talking about a beta here. And that the packages being de-installed were installed from CLI. So maybe the skill level is a little higher than it will be with production versions.

Given that venerable Synaptic PM is in the Ubuntu repositories, maybe the instructions should include installing it...sudo apt-get install synaptic. That installation pulls in a bunch of dependencies, and it may require activating repositories. Activating repositories appears to work okay with KPackageKit.

If you agree about using Synaptic...

Use your instructions for de-installing with Synaptic.

Add to instructions...
If Synaptic is not installed, open a Terminal window and use apt-get to install it (sudo apt-get install synaptic). You may need to install some dependencies for Synaptic. If asked, approve adding the dependencies.

If apt-get complains that Synaptic is not available, launch KPackageKit and enable all Ubuntu repositories by checking the appropriate boxes in the settings page. In a terminal window, update repositories with "sudo apt-get update", and retry the Synaptic installation.

Whaddya think?
Comment 5 Thorsten Behrens (CIB) 2010-11-29 02:27:22 UTC
Um, David, I see no attachment on this bug?
Comment 6 David Nelson 2010-11-29 03:06:49 UTC
Created attachment 40629 [details]
Original version of the readme, without subsequent edits in progress to take account of Carl Symons' comments

Original version of the readme, without subsequent edits in progress to take account of Carl Symons' comments.
Comment 7 David Nelson 2010-11-29 03:07:36 UTC
Thorsten, maybe check the first message in the thread. In any case, I will shortly be posting a new version taking account of Carl's comments and some additional proofreading by Sigrid Carrera.

Meanwhile, I have a problem: my instructions for installing a language pack DO NOT WORK... Could someone put me right about this?

The current version of the file is attached to this message... hopefully... ;-)
Comment 8 David Nelson 2010-11-29 03:39:40 UTC
Thorsten, I will shortly be posting a new version taking account of Carl's comments and some additional proofreading by Sigrid Carrera.

Cancel my last request about the lang pack problem... it works, but I had to restart my system first. You think simply logging out would be enough?
Comment 9 David Nelson 2010-11-29 09:38:26 UTC
Hi, 

I am submitting a revised version of the Linux readme that takes account of Carl Symons' comments and includes various other corrections. It would be great if a Linux expert could read through it, but I imagine it would only need minor corrections at worst.

Could you please include it with the Linux downloads as soon as possible? Thanks if so :-)
Comment 10 David Nelson 2010-11-29 09:42:10 UTC
Created attachment 40641 [details]
Updated readme for Linux downloads with fairly comprehensive installation instructions

Takes account of Carl Symons' comments regarding Synaptic, etc.... What do you think, Carl?
Comment 11 carlsymons 2010-11-29 10:58:18 UTC
Right-click within the directory and choose “Open in Terminal”. A terminal window will open.

With Kubuntu, this doesn't work.

Recommend:
If you use a file manager other than Nautilus, there may be a different way to open a terminal window. For example, with Dolphin, select "Menu > Tools > Open Terminal.

4) (installing desktop-integration). Command should be:
cd desktop-integration

After 7)
To ensure the cleanest-possible removal of a previous installation of LibreOffice, you can optionally also execute the following command...

recommend adding as follows:
...optionally also execute the following command in a terminal window...

---------
High praise for the way you handled adding Synaptic PM if necessary. I checked out the process and it works just as described.
Comment 12 Thorsten Behrens (CIB) 2010-11-29 11:44:20 UTC
Cool, thanks a lot for going after this - since we need to announce string freeze Real Soon Now, I'd ask for a consolidated version no later than tomorrow 08:00 UTC, such that I can review & commit it to the upcoming RC1. Please just assign this bug to me when you think it's ready.
Comment 13 carlsymons 2010-11-29 12:40:30 UTC
(In reply to comment #12)
> Cool, thanks a lot for going after this - since we need to announce string
> freeze Real Soon Now, I'd ask for a consolidated version no later than tomorrow
> 08:00 UTC, such that I can review & commit it to the upcoming RC1. Please just
> assign this bug to me when you think it's ready.

It feels quite useful now. I'm satisfied that most of the installation questions and confusion will be circumvented. Of course there will be issues that have not been anticipated, and people who don't understand or whatever. The LibO users list should be able to handle those.

Thank you, David, for making this happen. It's your baby to assign to tbehrens@novell.com when you're happy.
Comment 14 LeMoyne Castle 2010-11-30 03:27:50 UTC
The instructions seem clear and easy to follow but one thing pops out.  The links in the attachment are for the beta3 packages so they need to be changed in the instructions for the release.  Conversely, if this is also to be the installation readme for beta releases it needs the beta "backup and then install at your own peril" warning. I am assuming that we need both versions because I also assume beta releases will keep happening fairly frequently.  

I tried these instructions on Ubuntu 10.04 and noted only the step 4 cd desktop-integration and can't right click to open Terminal in Ubuntu that Carl found.  

Beta 3 installed like a charm with dpkg -i *.deb which makes me wonder about https://bugs.freedesktop.org/show_bug.cgi?id=31747 - broken debian files.  Previously I (thought I had to) edit the control files and re-build the packages to get them to install one by one.  Thanks for the instructions.  -- LeMoyne
Comment 15 Thorsten Behrens (CIB) 2010-11-30 13:53:45 UTC
Ok lads - updated readme more or less along the lines of David's text. With one notable exception - I left out the entire installation instructions.

Rationale: any user able to read those instructions obviously already successfully finished the installation. Since the information is helpful & excellently written - can we put that into the wiki & link it from the download page (someone volunteering for the former, I volunteer for the latter?)

Additionally, raw readme file attached - for further refinements, edits against that file much appreciated.
Comment 16 Thorsten Behrens (CIB) 2010-11-30 13:55:10 UTC
Created attachment 40681 [details]
Raw readme file

Actual readme as we'll have in RC1
Comment 17 carlsymons 2010-11-30 16:17:35 UTC
(In reply to comment #15)
> Ok lads - updated readme more or less along the lines of David's text. With one
> notable exception - I left out the entire installation instructions.
> 
> Rationale: any user able to read those instructions obviously already
> successfully finished the installation. Since the information is helpful &
> excellently written - can we put that into the wiki & link it from the download
> page (someone volunteering for the former, I volunteer for the latter?)
> 
> Additionally, raw readme file attached - for further refinements, edits against
> that file much appreciated.

Hello Thorsten,

The readme is in the extracted folder, which a user could get to before they install. However, I think putting this in the wiki is preferable. It provides one place to manage the information (such as changing the file names and extracted folder names). Better solution!

This also affords people the ability to look at the installation & de-installation procedures prior to further commitment.

Is there a LibO reader for the readme.xrm file? One, that is that doesn't have all the XML noise?

I'm okay with transferring the final product to the wiki, if no objections to this approach. Target page - http://wiki.documentfoundation.org/Beta3
Comment 18 David Nelson 2010-11-30 21:53:10 UTC
The whole purpose of me submitting this bug report was TO PROVIDE INSTALLATION INSTRUCTIONS, as a follow up to complaints on the mailing lists. It is TOTALLY ABNORMAL to ship a download such as this one without download instructions.

It took me a few hours to write them, and you just discarded them
Comment 19 David Nelson 2010-11-30 21:59:09 UTC
The whole purpose of me submitting this bug report was TO PROVIDE INSTALLATION
INSTRUCTIONS, as a follow up to complaints on the mailing lists. It is TOTALLY
ABNORMAL to ship a download such as this one without download instructions.

It took me a few hours to write them, and you just discarded them. FOR WHAT REASON? I am thoroughly irritated about this.

I request you to INCLUDE THE INSTALLATION INSTRUCTIONS WITH THE DOWNLOAD.
Comment 20 David Nelson 2010-12-01 02:19:19 UTC
Hi, 

As per Thorsten's request, I have posted the installation instructions at 

http://wiki.documentfoundation.org/Installing_LibreOffice_on_Linux

However, IMHO, the installation instructions should also be included in the stand-alone Linux downloads, in case the user is offline from the Internet.

I have edited the text to take account of Carl Symons' most-recent comments.

I am uploading the new text in .odt form and in .txt form. I recommend including the .txt file in the downloadable .tar.gz/.zip archives as a replacement for the current outdated readme.

The directory names are for the beta 3 and will need editing for the RCs and the final release. But I don't have the directory names for the RC downloads, so someone would have to deal with this...

As a general comment, IMHO, there should ALWAYS be standalone downloads for Linux, even after distribs start to include LibreOffice in their repos, to *guarantee* that the software is *always* available for all distribs and for all users...
Comment 21 David Nelson 2010-12-01 02:22:59 UTC
Created attachment 40693 [details]
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives

Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives. Takes account of Carl Symons most-recent comments.
Comment 22 David Nelson 2010-12-01 02:25:57 UTC
Created attachment 40694 [details]
This is the actual .txt readme that should be included in the .tar.gz

This is the actual .txt readme that should be included in the .tar.gz/.zip downloadable archives with stand-alone installation packages for Linux
Comment 23 David Nelson 2010-12-01 03:30:15 UTC
Created attachment 40695 [details]
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives
Comment 24 David Nelson 2010-12-01 03:31:47 UTC
Created attachment 40696 [details]
This is the actual .txt readme that should be included in the .tar.gz/.zip download
Comment 25 carlsymons 2010-12-01 09:06:03 UTC
(In reply to comment #18)
> The whole purpose of me submitting this bug report was TO PROVIDE INSTALLATION
> INSTRUCTIONS, as a follow up to complaints on the mailing lists. It is TOTALLY
> ABNORMAL to ship a download such as this one without download instructions.
> 
> It took me a few hours to write them, and you just discarded them

David,

This approach does not discard the instructions. It is a matter of where the information most usefully lives. The ReadMe file in the tar file can point to the WikiPage that has the instructions. And the WikiPage is printable (copy&paste-able). The packaged ReadMe can feature boldly that the user is advised to visit the WikiInstallation site for up-to-date information.

The alternative is to have a ReadMe that changes with each release. So that change becomes a task that someone needs to remember. In addition, once the detailed installation instructions are distributed, they are gone. They cannot be amended. If an error is discovered subsequently, there is no reasonable way to patch the ReadMe.

I appreciate your work and concern. I put in some time too, although not as much or as detailed as yours. Based on several projects supported by WikiResources, I'm confident that this approach will serve users.
Comment 26 David Nelson 2010-12-01 11:52:18 UTC
Created attachment 40714 [details]
Updated readme (in .odt) for downloadable Linux .tar.gz/.zip archives
Comment 27 David Nelson 2010-12-01 11:53:12 UTC
Hi Carl, guys,

My 2 cents would be that it's important to ship the instructions physically included with the download. Potential users of the download might not have easy Web access...? Plus, IMHO, providing installation instructions is a best practice...

However, I also understand your point about 1 more thing to track, maintain and update before a release. It's a tough call, but I still come down on the side of physical inclusion. 

As a member of the documentation team, I'm willing to commit to taking on this job, and to be there to liaise with you devs about it, if that is any reassurance to you.

By the way, my previous post that you quoted went off a bit too fast after I hit the send button too early, and it's true that I was a bit heated about it because of the surprising number of hours of work involved for this one "minor little readme"... ;-) I did apologize personally to Thorsten about that.

In any case, you will have seen that I have also created a wiki page with the instructions part of the readme...
Comment 28 David Nelson 2010-12-01 11:54:13 UTC
Created attachment 40715 [details]
This is the actual .txt readme that should be included in the .tar.gz/.zip download
Comment 29 carlsymons 2010-12-01 14:59:28 UTC
(In reply to comment #27)
> Hi Carl, guys,
> 
> My 2 cents would be that it's important to ship the instructions physically
> included with the download. Potential users of the download might not have easy
> Web access...? Plus, IMHO, providing installation instructions is a best
> practice...
> 
> However, I also understand your point about 1 more thing to track, maintain and
> update before a release. It's a tough call, but I still come down on the side
> of physical inclusion.

I see nothing wrong with including installation instructions with the tar file. It's just that those are more difficult to keep current. Perhaps there could be a line in the installation piece of tar advising the user to check the wiki for any late-breaking instructions.

Lately within our projects, we have been capturing long term shared knowledge in wikis, with discussions in bugtrackers or forums.

As the LibO project gains momentum, installation will probably become easier and there will be less need for the level of detail we created.

> 
> As a member of the documentation team, I'm willing to commit to taking on this
> job, and to be there to liaise with you devs about it, if that is any
> reassurance to you.

That's great. Is there a way that this task could be memorialized elsewhere in addition to your reminders? Is there some sort of task manager associated with the LibO project? It would be nice for you to be able to shed the responsibility at some point.

> 
> By the way, my previous post that you quoted went off a bit too fast after I
> hit the send button too early, and it's true that I was a bit heated about it
> because of the surprising number of hours of work involved for this one "minor
> little readme"... ;-) I did apologize personally to Thorsten about that.

No harm. Your consternation is understandable. I was also pretty sure that Thorsten has the best of intentions and valid points as well. Working together, we can sort through almost anything.
> 
> In any case, you will have seen that I have also created a wiki page with the
> instructions part of the readme...

I saw that someone had done that. Thank you.
Comment 30 Thorsten Behrens (CIB) 2010-12-01 16:02:43 UTC
Created attachment 40718 [details]
Updated raw readme.xrm

Current state of affairs for readme as it is in the repositories for 3.3. Many thanks to all involved here, for a much improved text. I apologize for my earlier misunderstanding, this thing is indeed easily accessible, inside the download tarballs.

Two things remain: the bigger one - I left out the whole uninstallation section for the while (it does not preclude later addition at all) - are we really sure we want to impose synaptic on everyone? The whole instructions are already at a level that may well be frightening for the ordinary user we're targetting.

A smaller one - I tried to use ellipses, general statements, and left out version numbers altogether. Having to edit that manually for *every* milestone will simply not work out. Besides, that at least for final releases, you want all of that translated, i.e. that's the work times 100.

For me, it would be much easier to receive updates as an edited readme.xrm - will try to incorporate changes posted differently still, but it may take longer.

Again, thanks to all of you, I think the readme already is a vast improvement over previous versions!
Comment 31 Thorsten Behrens (CIB) 2010-12-01 16:07:31 UTC
David, a procedural note - both html and txt file will currently be generated from the mentioned readme.xrm file. So adding it in one form is enough here - of course, preferably directly in .xrm.
Comment 32 carlsymons 2010-12-01 16:29:57 UTC
(In reply to comment #30)
> 
> 
> Two things remain: the bigger one - I left out the whole uninstallation section
> for the while (it does not preclude later addition at all) - are we really sure
> we want to impose synaptic on everyone? The whole instructions are already at a
> level that may well be frightening for the ordinary user we're targetting.

Regarding Synaptic, damned if you do, damned if you don't. The non-Synaptic instructions require sudo dpkg --remove or --purge on each individual piece. It is my understanding that there is no wildcard capability with dpkg removals; if this is not the case, then CLI might be the way to go.

The default package manager in Kubuntu does not behave well in de-installing the LibO components. So it seemed to me that it was CLI or Synaptic. Synaptic is not installed in the default Kubuntu package.

This may be a case where the wiki, forum or the user mailing list would be more effective. I was looking at making the process as explicit as possible. The downside is that the instructions may be daunting. Installing Synaptic involves installing quite a number of companion packages. Looking at the dependencies, there don't seem to be that many, but when I install it on a fresh set up, it seems like it wants 20 or so additional packages.

I wonder if there's a way to include a de-installation script in the installation package instead of those hefty instructions. Is it absolutely necessary to take out the previous version before installing?

Tricky situation.   

> 
> A smaller one - I tried to use ellipses, general statements, and left out
> version numbers altogether. Having to edit that manually for *every* milestone
> will simply not work out. Besides, that at least for final releases, you want
> all of that translated, i.e. that's the work times 100.
> 
> For me, it would be much easier to receive updates as an edited readme.xrm -
> will try to incorporate changes posted differently still, but it may take
> longer.
> 
> Again, thanks to all of you, I think the readme already is a vast improvement
> over previous versions!
Comment 33 Rogerio Luz Coelho 2010-12-24 06:48:25 UTC
(In reply to comment #32)
> (In reply to comment #30)
> > 
> > 
> > Two things remain: the bigger one - I left out the whole uninstallation section
> > for the while (it does not preclude later addition at all) - are we really sure
> > we want to impose synaptic on everyone? The whole instructions are already at a
> > level that may well be frightening for the ordinary user we're targetting.
> 
> Regarding Synaptic, damned if you do, damned if you don't. The non-Synaptic
> instructions require sudo dpkg --remove or --purge on each individual piece. It
> is my understanding that there is no wildcard capability with dpkg removals; if
> this is not the case, then CLI might be the way to go.
> 
> The default package manager in Kubuntu does not behave well in de-installing
> the LibO components. So it seemed to me that it was CLI or Synaptic. Synaptic
> is not installed in the default Kubuntu package.
> 

As I have updated in the wiki: 

sudo apt-get purge libreoffice? 

or 

sudo aptitude purge libreoffice? 

This "?" is the wildcard for the apt-get program, I don't use .rpm so I don't know how to proceed with them but for my understanding the yum commando has something similar 

Rogerio
Comment 34 Thorsten Behrens (CIB) 2011-03-25 03:37:40 UTC
No updates in a while, let's consider this fixed.
Comment 35 Björn Michaelsen 2011-12-22 05:35:35 UTC
Remove infoprovider from closed and resolved bugs.
Comment 36 Björn Michaelsen 2011-12-22 05:49:27 UTC
RESOLVED, FIXED or CLOSED bugs cant be KEYWORD NEEDINFO.