SLAC
ESD Software Engineering Group
| DOCUMENTATION AND WEB SUPPORT |
Web Support Design |
| SLAC Detailed |
| SLAC Computing |
| Software Home |
| Software Detailed |
| Documentation and Web Support Home |
| SLAC
ESD Software Engineering Group |
||||||||||
| |
|
|
||||||||
This is a design document
for ESD Software’s Web documentation.
Contents: Introduction, Problems
and Solutions (File
Organization,
Easy
Publication, Network
Independence, Other
Problems)
Although documentation
is a necessary part of development, contributing to our present knowledge
base can be a daunting task. First
of all, there is the question of a document’s existence and if so where to
find it. Currently, the ESD Software Web pages are not sufficiently organized
so that publication and retrieval is well understood.
Second, although most document writers work on Windows-based platforms,
the documentation itself is in AFS space.
There is a lack of user-friendly cross-platform publishing tools.
Another problem with the
current location(s) of our documentation is its dependency on AFS and SCS. In the event of a network disconnect, documentation
required to operate the accelerator must be available to Operations.
The requirements that will solve the problem of publication retrieval, uncomplicated addition to the current knowledge base and network independence are determined.
As projects and operating
platforms have multiplied, project owners have developed their own methods
of organization. The number of variables
that require consideration further complicates the matter. Is this a SLAC-only document? Is this a general document or does it apply
to a specific project?
A general file organization
hierarchy and structure must be established.
Specific Design Problems
and Solutions
1.
Problem: There
is no general scheme for correlating documentation subject to documentation
directories.
Solution: 1. On AFS
Web Server, create directories and index pages in these directories for keeping
user guides, requirements, and design documents:
·
$CD_SOFT/html/ug (http://www.slac.stanford.edu/grp/cd/soft/ug)
o
$CD_SOFT/html/ug/slaconly (symlink to slaconly/ug)
·
$CD_SOFT/html/pg (http://www.slac.stanford.edu/grp/cd/soft/pg)
o
$CD_SOFT/html/pg/slaconly (symlink to slaconly/pg)
·
$CD_SOFT/html/req (http://www.slac.stanford.edu/grp/cd/soft/req)
o
$CD_SOFT/html/req/slaconly (symlink to slaconly/req)
·
$CD_SOFT/html/design (http://www.slac.stanford.edu/grp/cd/soft/design)
o
$CD_SOFT/html/design/slaconly (symlink to slaconly/design)
·
$CD_SOFT/html/slaconly (http://www.slac.stanford.edu/grp/cd/soft/slaconly)
o
$CD_SOFT/html/slaconly/ug
o
$CD_SOFT/html/slaconly/pg
o
$CD_SOFT/html/slaconly/req
o
$CD_SOFT/html/slaconly/design
These
directories will be the default locations of such documents on Unix, if there
is no other project subdirectory in which they should be located, or before
that project subdirectory exists.
2. On
our local Windows IIS server, WEBMCC, symmetrically create directories and
index pages in these directories for keeping user guides, requirements, and
design documents. Because WEBMCC is
a SLAC-only server, the slaconly directory is not necessary:
·
\\webmcc\wwwroot\grp\ug (http://webmcc.slac.stanford.edu/grp/ug)
·
\\webmcc\wwwroot\grp\pg (http://webmcc.slac.stanford.edu/grp/pg)
·
\\webmcc\wwwroot\grp\req (http://webmcc.slac.stanford.edu
/grp/req)
·
\\webmcc\wwwroot\grp\design (http://webmcc.slac.stanford.edu
/grp/design)
2.
Problem: Web
page hierarchy does not reflect folder hierarchy.
Solution: Create an index.html page in each subdirectory
of /afs/slac/g/cd/soft/html, and link that to the home page afs/slac/g/cd/soft/html
either directly, or indirectly through intermediate index pages. There doesn't
have to be a precise 1:1 correspondence in the directory structure to page
hierarchy, but it should be close.
Organization will be both project and type specific. When project specific html directories do exist, soft links should be created from these directories to those corresponding subdirectories of each project, so for instance $CD_SOFT/html/req/cmlog is a soft link which points to the directory $CD_SOFT/html/cmlog/req/.
|
Unix Web Home: afs/slac/www/grp/cd/soft/ index.html /ug /req /design /slaconly /aida … /xgrabsc |
|
|
|
|
afs/slac/www/grp/cd/soft/ug index.html aida@ cater@ … xgrabsc@ |
afs/slac/www/grp/cd/soft/aida index.html /ug /req /design /slaconly |
similar folders for /req, /design, /slaconly similar folder for each project
3.
Problem: Web pages are not standardized.
Solution: Go though all pages now in the subdirectories
of afs/slac/g/cd/soft/html, and add the standard ESD Software Engineering
Group Unix web page header on them at a minimum. If possible, apply the standards listed in the
template located at http://www.slac.stanford.edu/grp/cd/soft/stds/html/master.html.
4.
Problem: There
appear to be redundant folders.
Solution: We have both a CD_SOFT/html/slaconly and
a CD_SOFT/html/share/slaconly. Why do we have these two. If there's no good
reason, amalgamte them under just CD_SOFT/html/slaconly and fix the links.
Note, slaconly in the pathname tells the web server not to let anyone from
outside SLAC access the page. Seems like we don't need both slaconlys though.
Currently, the easiest way
to create a document using Microsoft Word or FrontPage and publish it to AFS
is by saving the document to the appropriate AFS folder using the OpenAFS
mounted file system. SCS does not currently
support the use of OpenAFS with the
Windows XP Operating System. Although
many individuals have made it work, SCS has warned that this will no longer
be possible once Windows XP is at its highest security setting.
So what does SCS suggest?
The SCS-supported tool provided for copying files is WinSCP (http://winscp.vse.cz/eng/index.php),
a freeware SCP (Secure CoPy) client for Windows which uses SSH (Secure Shell)
to safely copy files between a local and a remote computer. It works much like WS_FTP. A user must log in, find the destination folder
on the remote computer (AFS), then copy it over. If a user wants to update an existing document,
then the file must first be copied to the local computer for editing in Windows-based
editor, then copied back to AFS. The process is confusing and cumbersome.
Ideally, a knowledge base
contributor should be able to open a document in a browser, make edits and
publish quickly without having to memorize the exact location on AFS.
Specific Design Problems
and Solutions
1.
Problem: Publication
location is unclear because there are so many possible publication locations.
Solution: Web page locations and their purposes
will be organized as follows:
| |
What goes there |
Features/Limitations |
| afs |
·
All Unix project documentation
·
Individual Unix account pages (http://www.slac.stanford.edu/~username) |
·
Unix
·
Not WebDAV-enabled |
| Webmcc |
·
Mirror of AFS documentation (read-only)
·
Release announcements |
·
Windows
·
SLAC-only |
| www-user |
·
Individual Windows account pages (http://www-user.slac.stanford.edu/username) |
·
Windows
·
Public |
| www-group |
·
Index Panel
·
NLC Architecture, Networks and Software
·
Presentations/documentation that should
be visible to the public (ICALEPCS Epics, Fireside Chat) |
·
Windows
·
Public |
| Cd-server1 Web server |
·
This Web server will be retired.
Documents will be moved to the appropriate directories (ug, pg,
req, design on afs, webmcc, or www-group depending on its visibility
and content |
|
| www-mcc |
·
This Web server will be kept unchanged,
but new documentation should not be placed here |
|
2.
Problem: Authoring privileges are inconsistent.
Solution: Give the Software Group write access to
the Web pages, so documentation can easily be updated. Each publishing location should have an identified
“Advanced Author” who can set folder permissions. On AFS, this will depend on the ACL in each
directory under afs/slac/g/cd/soft/html/. The ACL is probably the same for
each subdirectory of afs/slac/g/cd/soft/html/, but still check which ACLs
are there, and whether everyone in the software group is able to write to
those directories. For Windows, verify
that the ESD Group has authoring privileges to http://www-group/cdsoft
and http://webmcc.slac.stanford.edu.
3.
Problem: A User Guide to help people understand methods
and locations for publishing does not exist.
Solution: Write a Users' Guide to ESD Software Group
Web Site. This should include:
1.
Help page for web page writing and publishing.
This should cover help for each of:
a.
Publishing to the Unix web space
under /afs/slac/g/cd/soft/html from XP. Include explicit instructions for
Netscape Composer and Macromedia Contribute.
b.
Writing and publishing to Windows
Web space.
2.
Guide to the directory scheme in place. That
is, list the special purpose directories CD_SOFT/html/ug, CD_SOFT/html/req,
CD_SOFT/html/design, and the other important directories we have in place.
A script will be written to create directories and symlinks for new
projects.
A compromise of the control
system’s security which would require us to disconnect from the SLAC network
or AFS incapacity are current examples of conditions under which an operator
would not be able to retrieve control system documentation.
A Web Server on the control-system
side of the firewall is required.
Specific Design Considerations
1. Question: Should the local server be Unix or Windows?
Discovery: There are two advantages of a Windows-based Web server over
a Unix server. The first is that SCS has agreed to support it remotely. The
second is that the current configuration for Windows servers that SCS supports
allows for publishing via WebDAV (Web-based Distributed Authoring and Versioning,
http://www.webdav.org/). WebDAV is a set of extensions to the HTTP protocol
which allows users to collaboratively edit and manage files on remote web
servers. Clients include Microsoft
Word and Microsoft Front Page. Although
a Unix Server would have eliminated cross-platform file copying, SCS will
only support AFS, not NFS. An AFS server
would not meet our disconnect requirement, and an NFS server would require
resources for maintenance.
Decision: We have purchased a Windows server, http://webmcc.slac.stanford.edu. It is physically located in our Computer Room.
2.
Question:Should documentation be written to AFS, WEBMCC, or both?
Discovery: Ideally,
document writers would be able to choose their publishing tool and write to
either Unix or Windows space.
However, constant mirroring is not possible.
The natural place for documentation to be housed is with the application
or project. As many of our applications
are in AFS, it follows that supporting documentation should be kept in AFS.
Decision: All documentation will be published to the
AFS directory /afs/slac/www/grp/cd/soft. All AFS documentation in this directory
will be mirrored to our new Windows IIS server, http://webmcc.slac.stanford.edu
which is physically located in our Computer Room. Mirroring will be accomplished
using GNU Wget (http://www.gnu.org/software/wget/wget.html),
a free network utility used to retrieve files using HTTP, HTTPS and FTP. Wget
will translate absolute URLs to the local web server while it recursively
mirrors the directories. WebDAV publication
to AFS is still under investigation, but FTP publishing is currently available
with tools such as Netscape Composer and Macromedia Contribute.
1.
Problem: Nodenames are visible to the public.
Solution: Move control-system detailed operational
pages to /afs/slac/g/cd/soft/html/slaconly, and fix links. Pages which should
be moved are those that include nodenames,
like "opi00gtw00", or "MCC.SLAC.STANFORD.EDU". This may
well entail finding all references to those pages and changing the link!
· Our software releases pages (http://www.slac.stanford.edu/cgi-bin/lwgate/CDSOFT-SW-RELEASES/archives/ and below are such pages that have node names and should be moved to slac-only. This is a cgi system, so moving it may not be trivial).
Programmers' Guides, Users' Guides, Requirements, Design, Papers, Administration, How-To, Hardware, IOC, Database
Author: G. DeContreras, 14-Apr-2003
Modified by: