On 06/08/2011 10:53 PM, Philip Olson wrote: > Hello Everyone, > > We recently received a request to document PHP + Azure. This is not something > we've done before, so let's discuss where this might go and how it may look > (and apply/plan this to similar services like EC2) in the future. We don't > want to get into a situation where we'll need to move sections around later > (broken links/translations/ids) so a little planning now will help. And > keeping them all together feels wise. > > We must also determine if we want to do this. I wasn't sure but Rasmus made > several convincing arguments. Users will benefit by sharing user-contributed > notes. And users want to know that PHP works "in the cloud" (and how) so > let's tell them about it. And the documentation should be brief, have plenty > of examples, and link elsewhere for further information. > > This is a slippery slope but at this point we could draw the line in the > cloud^Wsand with cloud computing. A section can talk a little about cloud > computing and then show where PHP fits in. This is where people will go after > hearing about how great clouds are. > > The appendix is the simplest place to store this but maybe we can come up > with a better location because the appendix has outgrown itself. The install > section comes to mind, where we'd create a new section next to OS. Windows > Azure, for example, would be listed under "Cloud Computing" and not with > install/windows in this scenario. However, 'install' limits the scope of the > conversation because we'll probably want to expand the entire topic. > > What do people think about this?
A couple of points to let people know what these "several convincing arguments" were. 1. I get asked all the time about how PHP works with the cloud. The people who ask me this don't really know what they are asking, but they have heard that the cloud is the future and they are worried that they will not be in the clouds with PHP. So the first argument related to this is that we can think of the various cloud environments just like we think about operating systems. Installing PHP in the various cloud operating systems isn't that different from installing PHP on the various local operating systems. 2. An intro, clear working examples, links to further docs and user-contributed examples. That's what people expect and like from our docs. I think we can bring this to more areas of interest to PHP users than keeping it strictly to only documenting extensions. But, like Philip said, it is a slippery slope. However right now there is an obvious way to game the system. Simply write a trivial extension, stick it in svn or put it on github/codeplex/wherever and now you are in. And in fact Azure has such a trivial extension: http://phpazurecontrib.codeplex.com/wikipage?title=php_azure.dll so even if we tell Craig not to put the Azure thing in the install section, he can simply submit documentation for the extension and put his Azure install blurb alongside his extension installation docs and everyone would be happy. However, if we take an honest look at this rather arbitrary restriction of only allowing extensions to have landing pages in the docs, it is exactly that, rather arbitrary. I think a better restriction is whether a topic is of general interest to PHP users. And here I think documenting how to install and use PHP with the various cloud services is something that is genuinely interesting to many users. Ok, so the "several" arguments was just two, I guess. -Rasmus
