We now lots of different ways that a document can be published in the VAO: the wiki, forum, blog, JIRA issue, mailing lists, public website or the document repository. This post suggests how these elements might work together.
The wiki (including Trac) serves as the internal web site. It provides an easy way to publish and organize information that we want to use in running the VAO. Though there may be exceptions, information here is generally not visible to the public. Limited effort are made to enforce style guidelines. Obsolete information is deleted (though available through the internal CM capabilities of the wiki). Organization is according to the functional needs of the VAO, notably through WBS elements and software development projects.
The document repository is intended to provide a standard location for finding all formal documentation in the VAO. Any document that have a version number (and some that don't) should be available in the repository. All versions of a document re available. My recollection is that the current plan is to have the repository basically be a wiki page with lots of attachments, but I may be out of date. If this is still the approach the documents in the repository would be an exception to the visibility rules for the wiki since they would be visible to the public.
The forum provides an area where questions and comments may be asked and discussed. The post initiating a forum discussion may require a fairly long prologue setting up a context or giving some background information, but an archetypical post would boil down to a fairly short question or comment: "How do I get the list of sources I extracted from the portal into the cross-correlation engine?" "Wouldn't it be nice if I could see the positions in galactic coordinates?" "The SED service crashes on my Linux xxx box."
A JIRA ticket implicitly describes both a situation and a resolution. A ticket is the appropriate document to initiate and monitor a specific action by the VAO team. If no specific action is intended then a JIRA ticket is not the appropriate vehicle.
Mailing lists are the only documentation framework outside JIRA which demands attention from the user. Thus they are used to make sure that people are informed when meetings are to take place or when critical documents are to be reviewed. Generally other formats are better for structured discussion of issues, especially the Wiki and forums.
The web site is what we present to our science and EPO communities. The web site may reference the document repository for documentation of some user services but probably does not have much visibility into the other documentation classes discussed here. Ray has suggested that we might use Trac pages for software documentation. Personally I'm a little dubious here. Good documentation for a service as seen by users is rather different from that for developers. I also think that it's important that documentation look like it belongs to the service its documenting. Typically a web page will use lots of internal anchors and such. So my suspicion is that on-line documentation will tend to be either complete documents from the repository or specially crafted using the overall web site guidelines for the VAO.
Finally the blog is used for essays: what does a member or team from the VAO think about something. The blog can be documentation but tends to be developmental rather than descriptive. E.g., suppose the portal effort goes off and tries a couple of different techniques for coupling to the cross-correlation service. SAMP for some reason doesn't work and a VOSpace-based approach is adopted. A blog entry describing this process could be invaluable. It doesn't really belong in the documentation of the service as developed, but a blog post provides a place to say why a given approach was adopted. Similarly the blog can be used to talk at length about how we might do something complex (say mesh our various documentation frameworks to pick a random one:) in a non-authoritative way.
To give a concrete example of how all of these might work together consider the current discussion of how we will build web pages. I tried to kick off the discussion with a blog post trying to summarize what we think we agree on and what questions need to be addressed. Other's are free to comment on or edit the post. If they have some substantial thoughts themselves, a parallel post can be provided. If we've more than a trickle we'll want to add tags to discussions to group them. Over the course of the next month, as we begin to understand the boundaries of what we are trying to do, we may start a wiki page with an outline for the policy document. A post to the team mailing list lets everyone know what's happening so this can be reviewed by and edited by the team and a version can be agreed upon. At that point the document should be copied in some fashion, TBD, to the document repository. It may require purchase of specific software by one or more members of the VAO and a JIRA ticket can be issued for each such requirement. This discussion manifestly affects the appearance of the public web pages we have, but no reference to it is necessarily visible in those pages. Once the process begins a VAO member with a question about how to do a specific step in the documentation process may enter a query in the forum (especially if we have an inward facing version of the forum) and other members of the team can respond with suggestions.
Tuesday, August 2, 2011
Building Web Pages for the VAO
Many of us in the VAO will be involved in writing web pages. This post discusses how we work together to build a coherent and consistent web environment, discussing what has been agreed and trying to identify questions that we need to address.
Classes of Web pages.
Per the discussion of the July team meeting, we define three classes of web pages according to the anticipated audience.
Where do web pages go: physical?
Where feasible web pages should be included on the VAO's primary Web site (hosted at Caltech). Documentation, software downloads, and simple forms can all be easily accommodated by the main web site. Science capabilities, e.g., the VAO portal and cross-match services may need to be hosted on other machines. This should be discussed in the operations plan for the service.
Where do web pages go: virtual?
All VAO web pages should appear with in the usvao.org web space. This will naturally follow when web pages are included on the Caltech host. If a service must be hosted remotely, then a web-address of the form xxx.usvao.org shall be aliased to the appropriate site.
How do we define the 'xxx's?
Currently we have help.usvao.org, and dev.usvao.org (which both link to internal sites).
How do we build web sites?
Do we want a content management system? Do we build web sites as an operation on the SVN repository?
Do we want a standard form support system (a la ColdFusion)?
How do we ensure uniformity among our Web sites?
This would be one goal for a content management system.
Alternatively we could have standard CSS and HTML templates that all web sites are required to integrate possibly using different techniques.
What are the design elements that appear on VAO web pages?
Logo's, institutional references, style, ...
A general web design framework would be nice. Probably User Support's role to answer. One role of the content management system is to separate the design elements from the content, but that is unlikely to be entirely successful.
Do we need to identify logical cross-references?
One suggestion during the team meeting was that we should use logical names for links within the VAO (i.e., from the portal to the cross-match service) and have these resolved at some point. This would allow use to each change locations for given services without breaking links. It would also allow us to provide some support for handling references to services that are not yet available.
Do we want to do this? If so how and at what level do we define these links?
Who builds web sites?
Can't place all of the burden on Sarah.
Automated creation by content management system in fashion similar to Jenkins testing framework?
Multiple authorized users at Caltech site?
Who authorizes creation and modification of web site?
At the team meeting we discussed this as a CMB responsibility and that is certainly the case for significant changes. However if we want a responsive we site we probably need to allow much more freedom for at least some areas of the web site (e.g., latest news, personnel, faq). Nor do we wish typo fixes to required CCB approval.
Added:
Sarah brought up some issues in the telecon including:
Classes of Web pages.
Per the discussion of the July team meeting, we define three classes of web pages according to the anticipated audience.
- Internal web pages are intended only for the eyes of members of the VAO. This may include the VAO wiki and raw Trac and JIRA web pages along with this blog.
- Public web pages are web pages intended to serve our role in the science community. This includes our science services, documentation, help pages, newsletters, forum....
- Outreach web pages are pages specific to our EPO efforts which are intended for non-science users.
Where do web pages go: physical?
Where feasible web pages should be included on the VAO's primary Web site (hosted at Caltech). Documentation, software downloads, and simple forms can all be easily accommodated by the main web site. Science capabilities, e.g., the VAO portal and cross-match services may need to be hosted on other machines. This should be discussed in the operations plan for the service.
Where do web pages go: virtual?
All VAO web pages should appear with in the usvao.org web space. This will naturally follow when web pages are included on the Caltech host. If a service must be hosted remotely, then a web-address of the form xxx.usvao.org shall be aliased to the appropriate site.
How do we define the 'xxx's?
Currently we have help.usvao.org, and dev.usvao.org (which both link to internal sites).
How do we build web sites?
Do we want a content management system? Do we build web sites as an operation on the SVN repository?
Do we want a standard form support system (a la ColdFusion)?
How do we ensure uniformity among our Web sites?
This would be one goal for a content management system.
Alternatively we could have standard CSS and HTML templates that all web sites are required to integrate possibly using different techniques.
What are the design elements that appear on VAO web pages?
Logo's, institutional references, style, ...
A general web design framework would be nice. Probably User Support's role to answer. One role of the content management system is to separate the design elements from the content, but that is unlikely to be entirely successful.
Do we need to identify logical cross-references?
One suggestion during the team meeting was that we should use logical names for links within the VAO (i.e., from the portal to the cross-match service) and have these resolved at some point. This would allow use to each change locations for given services without breaking links. It would also allow us to provide some support for handling references to services that are not yet available.
Do we want to do this? If so how and at what level do we define these links?
Who builds web sites?
Can't place all of the burden on Sarah.
Automated creation by content management system in fashion similar to Jenkins testing framework?
Multiple authorized users at Caltech site?
Who authorizes creation and modification of web site?
At the team meeting we discussed this as a CMB responsibility and that is certainly the case for significant changes. However if we want a responsive we site we probably need to allow much more freedom for at least some areas of the web site (e.g., latest news, personnel, faq). Nor do we wish typo fixes to required CCB approval.
Added:
Sarah brought up some issues in the telecon including:
- What is the relationship with the document repository?
- We need to identify actual people involved at various steps.
Ani noted in the comments that we will want to have an expedited process by which the web master can update the page with the CMB's blessing without having to go through an actual meeting.
Wednesday, July 27, 2011
Subscribe to:
Posts (Atom)