1242216 - windows build documentation issues

Status: REOPENED

(Bugzilla :: Documentation, defect)

Description

[aux1]

Attachment: Install solutions.docx

User Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36 OPR/34.0.2036.50

Steps to reproduce:

On my fourth try, I succeeded in installing Bugzilla.


Actual results:

See attached file


Expected results:

See attached file

Comment 1

[Frédéric Buclin]

Your documentation seems to refer to some older documentation, so it's a bit hard to know what you are talking about in some comments. For instance, section 12.1 doesn't exist, see http://bugzilla.readthedocs.org/en/latest/installing/windows.html

Please make sure to use this link to install Bugzilla on Windows, and keep in mind that Strawberry Perl is not the same as ActivePerl.

Comment 2

[aux1]

I don't think this is "older documentation" though it would seem to be different. What I am looking at is headed "Bugzilla Documentation  Release 5.0.2+" by "The Bugzilla Team" and dated "December 29, 2015"

Comment 3

[Frédéric Buclin]

Ah, I see. You are talking about the PDF documentation, which uses some different chapter numbers for the web and SQL servers sections compared to the HTML documentation.

Anyway, I disagree with most of your comments in your document. For instance, you neither need Visual Studio, nor MS Excel, nor Agent Ransack to make Bugzilla work. Some other statements are incorrect too, such as where to put instructions in httpd.conf or the URL to use to access Bugzilla (already mentioned in the documentation). The only relevant part is about the out-of-date documentation about the MySQL installer. But you already filed bug 1236682 for this.

Comment 4

[aux1]

Frederic,
First I think I should apologise about the right hand column heading "My solution". This might have been better titled "What I did". The intent was that having encountered the problem in the middle column, to make clear what I did to move on. Also recognising that the choice I made may indeed have contributed to subsequent problems. In other words I was certainly not saying that the actions I took where in any sense the 'best' actions. Only that the complete set worked, after many hours of trying alternative steps at each of the error messages etc. I encountered.

Secondly I need to inform you that I have worked in the computer industry for forty years, written thousands of lines of code, written many hundreds of pages of documentation, and, most pertinently, done many hundreds of windows installations, and some tens of Linux installations. I say all that not to make out that I know everything, which is very far from true, specifically in the area of Bugzilla installation. Rather to say that the statements I have made are based not only on tens of hours working through four iterations of attempts to install Bugzilla, but a life time of relevant experience, and should not be treated lightly.

Thirdly. I acknowledge that the manual contains a very large quantity of essential information, and recognise the work that has gone into providing this. However I assert categorically that starting from a clean Win 7 HP up to date install it is not possible to directly (I emphasise directly) follow the instructions in the manual and arrive at a successfully install. (I suspect that only people who 'know too much' have tested the instructions and filled in the gaps without even realising they have done so.) Each of the rows in my table corresponds to an error message, or a situation requiring decisions not covered by the manual. Some action not covered by the manual is required at each of these steps.

Lastly, I suggest that you focus on the "Problem" column instead of the mis-titled "My solution" column. I can assure you that all these events are real and as I recorded them.

Comment 5

[Dylan Hardison [:dylan] (he/him)]

Thanks for documenting what you went through to get Bugzilla installed on Windows! We don't get very much help with that platform. I haven't read the document yet, but I will do so shortly.

I'm re-opening this bug so that I can make sure the "problems" listed can be addressed in the current docs.

Comment 6

[Frédéric Buclin]

(In reply to aux1 from comment #4)
> However I assert categorically that starting from a clean Win 7 HP up
> to date install it is not possible to directly (I emphasise directly) follow
> the instructions in the manual and arrive at a successfully install.

You mention "problems" or decisions to make when installing git or MySQL. Our documentation is not the right place to explain the user how to install them. First of all, changes in their installers would make our documentation out-of-date. Secondly, the git own documentation and the MySQL own documentation are better places to get help to install them if the installers and confusing to you. Some decisions may depend on what you try to do (real production server vs developer machine). So we only mention what is specific to Bugzilla.


> Lastly, I suggest that you focus on the "Problem" column instead of the
> mis-titled "My solution" column. I can assure you that all these events are
> real and as I recorded them.

Some of your "problems" are not problems, especially those you listed in sections 3.3.x. And about section 7.x, you already filed bug 1236682, which I marked as valid. So I'm not throwing away all your comments.