Zend Framework

It's good to have it, but it's not a stopper for releases

If it would be a stopper I would have set "BLOCKER" instead of "CRITICAL".

I added CHM generation to the build process of the manual for all languages.

It's now just a click... and with the HTML files for the manual also a HHP file will be generated.
This file is the project file for the MSHTMLHELPWorkShop.
With the call "hhc htmlhelp.hhp" the final CHM file will be generated.

Now only a batchfile has to be done which generates all CHM files from each language is wished.

What I am not able to do, is to integrate the CHM files into the homepage.
I will need help from anyone from Zend for this.

Assigned to Wil as the basework has been done and only Zend is able to integrate the CHM helpfiles into the ZF homepage.

Resetting 'fix version priority' and 'fix version' to be re-evaluated for next release.

Changed issue type to TASK.

The build process has already been finished 6 weeks ago but the chm files from the build have to be integrated into the homepage.

Updating to comply with new IT component conventions.

Thomas, I think I asked you this on IRC, but just for the record. . . Would you mind if we built the CHM docs and put it next to the PDF version of the manual on zend.com? http://www.zend.com/community/downloads
I ask because this would be a registration-required download, as is the case with the current PDF. The advantage is that we'll be able to serve it using our CDN.

Wil, why are CHM and PDF versions unavailable on the Zend Framework site out of curiosity? Can't they be served from the CDN there as well, like the framework itself?

Wil:
As said in past,
I see no advantage of having PDF and CHM extracted to another location than ZF itself.
Users would not find the download if it is not available directly beside the normal HTML manual download on ZF homepage.

Michael and me have already worked on both formats, and building the manuals is one single command line call. Actually Michael made the manuals for 1.7.2 available through his blog for all languages.

The point for me is a simple one:
Why seperate the build process when all can be done with one call. A seperation would be only another point of failure. The other point is usability for our users. A manual which will not be found on the first look is no good manual.

Matt: Because we want to offload some of our bandwidth to our CDN, which is not set up for framework.zend.com yet (it is expensive). Also, we get valuable registrations from the PDF download, which makes it much easier to justify the resource investment for Zend.

Wil, i can give you some informations about downloads on my site (for PDF & CHM format). In my mind, when PDF and CHM will be on official site, i won't need to propose them on my site.

Thomas: Plenty of people have found the PDF doc, which is linked to on the main docs page: http://framework.zend.com/docs. From our perspective, generating these additional documentation formats involves some extra effort with every build + the effort to expose it in the right place on the site. Registrations that we get from zend.com are much more valuable to Zend than downloads from framework.zend.com + they are faster since they are on the CDN. In short, it will be much easier for me to justify using Zend resources to put it on zend.com, but if you're not OK with that then I won't use your good work to drive registrations. If you'd rather not have them on zend.com, I think the community can handle providing this format for the time being.
Let me know so we can get resolution on this issue.

Is there at least a link on framework.zend.com to direct people to the PDFs with a notice saying "Zend.com registration required"?

Where we place it does not matter... The thing is usability and simplicity. They have to be found without searching.

Actually when downloading a new release there is no way to get the pdf and chm downloads also from the download section. It's not intuitive to be found on the homepage. Same for FAQ as I mentioned in past.

Also there is no way to get the PDF's for different languages. Also PDF is only available for 1.6 in english. It's the same building process... only one commandline to get all formats in all languages.

If you think it's better to have the community to provide these downloads on their private homepages as it's done for now I must strictly disagree. This shows just that there is not much effort to make things easier for customers.

Btw: The download page on Zend.com is quite un-intuitive.

As summary:
Having the downloads on CDN is no problem... the thing is that we should provide this formats somewhere. A registration would not be a blocker for most people when they know that they get what they requested.
The manuals should be available with the build or at last one/two days after it.

OK, then I will work on this with you, Thomas. I'm leaving this issue open since I'd like to resolve this in the next few weeks. Thomas, I will read Mickael's proposal now, then we should coordinate over IRC and/or mail.

Great... I think the number of votes and watchers on this issue shows that people really wants it to be done.

If we could do it the same time as the newly discussed manual improvements it would be a really big step forward to a simplification for ZF users.

I assume this one is for Matthew.

Has anyone considered using PHP's PhD to create the documentation? The XSLT process is considerably slower and power hungry. I'm on Windows with Cygwin and the ZF documentation started at 15:09 and is still going strong at 15:24. The PHP documentation, all 10,500+ files doesn't takes around 6 minutes and the CHM build around 2 minutes.

@Richard: we're actually using PhD to generate the packaged HTML manual pages, as well as the ZF online docs. I will be investigating CHM and man page generation for upcoming releases. I have not changed the current Makefiles yet, but have posted instructions to the fw-docs list.

Yes, it's tremendously faster – I was seeing build times of anywhere between 6 and 20 minutes per language with xsltproc, and can now do each language in 30s or less.

FYI, I believe the mailing list post regarding PhD that Matthew mentioned is this one: http://zend-framework-community.634137.n4.nabble.com/New-capabilities-via-PhD-td1460442.html