[rt-users] unordered mismash of upgrade instructions

[Jo Rhett]

On 11/26/2014 05:32 PM, Jo Rhett wrote:
>> I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
>> liking the changes. Glad to see RTFM integrated. My one big question
>> here that I think the documentation could definitely improve upon, is
>> what order to do the changes in?  There are changes in every one of
>> these pages and there’s no clear outline for which ones go first.
>> 
>> https://www.bestpractical.com/docs/rt/4.2/README.html
>> …(list of files)...

On Dec 4, 2014, at 2:08 PM, Alex Vandiver <alexmv at bestpractical.com> wrote:
> Step (2) and (6b) of this address the other files.

These are the sections of which my complaint is generated. Yes, they list the entire stack of docs which should be read. That’s how I knew the list I posted. But there is no ordering information included here.

> The top of
> UPGRADING.mysql even tells you to start there. A bug in the POD -> html
> (now fixed) causes it to not show up in the website, but it's in the
> shipped docs/UPGRADING.mysql in the source tarball.

Yes the revised page is more clear. It’s still not the easiest to track instruction. You could easily demonstrate this with screenshots in a way that someone could follow.

Furthermore, this phrasing is very confusing and implies that nothing else in the documentation applies.

> 	• You are upgrading RT from a version prior to 3.8.0, on any version of MySQL
> 
> 	• You are migrating from MySQL 4.0 to MySQL 4.1 or above
> 
> If neither of the above cases apply, your should upgrade as per the instructions in the README.

So if I am upgrading MySQL 5.1 with RT 3.8.5 I shouldn’t read any farther, right?  I don’t think that’s what you intended to say.

-- 
Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.