Re: Documenting Cloud (and other) services

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