Section F.1 identifies two supporting documents that are included in the design. The second one, the "XSEDE Identity Management Client Application Setup" document, should not be a Google Doc. It needs to be delivered as a Web page somewhere in the XSEDE web space, preferably in the existing places that science gateways, service providers, and campus IT admins go for information about XSEDE.
So I agree that this doc is necessary and important, but I think the design doc should say something along the lines above about how the document is delivered and available to people who need it. It should also be clear that the target audience includes: gateway providers, service providers, and campus IT admins. (I'm not sure... Are there any other important users of XSEDE Web SSO?)
Thanks for the suggestions, Lee. The client setup guide being deployment documentation material, I believe it could live in SVN source directory, which has been the traditional repo for deployment docs. Would this work for Science Gateways and such? I am also curious what JP and others have to say. Thanks.
We often use Google for draft documentation that is delivered and deployed as PDF wherever it makes sense. We generally use SVN for snapshots and not as the final delivery location. Using this flow you draft in Google, snapshot for reviews and delivery in PDF, and deliver to customers as PDF.
If you want to try something more progressive you could try using StackEdit with Google Drive and deliver the Markdown documents as HTML.
JP
We also use Google to draft documentation that is delivered and deployed on the XSEDE website, as we've done for documentation on Globus.
My main concern is that we only use the Google doc as a draft. When we have an approved version, we need to deliver it. I'm not as concerned about the delivery as much as separating the drafting from the delivery. Though I do think that the delivery should be tailored to how the target audience expects to get their information and documentation from XSEDE already. We don't want to introduce new delivery methods, IMO, unless they're consistent across all messaging from XSEDE.
Hi Lee,
All the deliverables for XCI activities that I have worked on, were delivered in the "Deliverables" directory of the activity in SVN. From thereon they somehow make it into the Production space. Example:
http://software.xsede.org/production/gsi-openssh-server/latest/XSEDE-GSI...
There are a lot of other products under http://software.xsede.org/production/
such as two-factor.
There's also the XSEDE standard Deployment plan that either lists the deployment instructions directly or points to an external doc like the one for GSISSH mentioned above, which is publicly accessible.
Are you suggesting a different way of delivery?
Thanks,
venkat