Silicon Valley Linux User Group: Web Team Instructions

The SVLUG Web Team (part of SVLUG's core "Volunteers" group) performs the tasks that are usually thought of as the "webmaster". In fact, webmaster@svlug.org is just an alias for the volunteers@lists.svlug.org mailing list. We expect Web Team volunteers to be trustworthy, able to work in a team, and have some prior experience. Though not everyone can be accepted for the Web Team, people interested in volunteering to help SVLUG will still find numerous activities where they can help, such as at the meetings and installfests.

Organization of the Group

We divide Web tasks between these coordinators:

Web Content Coordinator

• The wording and content of the SVLUG Web site is under the Web Content Coordinator. Responsibility for adding and maintaining text and graphics belongs with and is delegated from this position. The Web Content Coordinator is Rick Moen, filling in for an over-occupied-with-real-life Heather Stern. Heather was aided by Joyce Traugott.

Web Design Coordinator

• The look and feel of the SVLUG Web site is under the Web Design Coordinator. (This was a new role added at the 4/27/1999 Web Team meeting, and currently unoccupied.) The Web Design Coordinator was Amy Abascal. Real life has forced her away from volunteer projects, but we are still enjoying her Web site design.

Web Software Coordinator

• The software that makes the system run, including the Apache HTTPD server, CGI programs, embedded mod_perl scripts and Web-related cron jobs, are under the Web Software Coordinator. Responsibility for adding and maintaining Web software belongs with and is delegated from this position. Lisa Corsetti, our last Web Software Coordinator, now has a beautiful child and is waaaay too buy for volunteer work. The task has gone un-tended for a while.

To join the Web Team, contact webmaster@svlug.org, or talk to the appropriate coordinator for the kind of work you prefer to do. Any SVLUG members interested in Web Team affairs, whether Web Team members or not, should consider completing the "Subscribing to Volunteers" form on the Volunteers mailing list page. There is also a read-only reference archive of the formerly separate web-team mailing list's 2000-2005 postings, for continuity-of-knowledge purposes.

Web Team volunteers may work on content and/or software. Decisions that affect the whole SVLUG server should be run past the appropriate coordinator and/or reviewed on the Volunteers list. Any work that has to be done by / for SVLUG anyway should just be done. Use RCS to make sure that changes can be tracked and reversed if necessary.

[RM note: Much of what follows will become obsolete as we migrate to the wiki, but we're retaining it during the transition.]

Software That Web Team Volunteers Use

• Linux (obviously)

• SSH -- Secure Shell (SSH) is required to log into our server

• RCS -- Revision Control System, [attach:rcs_func.pdf overview] (19K PDF), [attach:rcs.pdf white paper] (330K PDF)

Web Content Tasks and Procedures

Keep SVLUG's Web pages up-to-date.
Or make sure someone does.

Where are the Web content files?

(There have been other virtual hosts in the past. We have only two at the moment.)

What is the Web Content Coordinator's role?

• The Web Content Coordinator gets to participate in the "herding of the cats", i.e., coordinating everyone who can update the Web site. Major Web content decisions are the Web Content Coordinator's to make -- though you'll probably want to put major changes up for review and comments, because consensus is important to make sure volunteers believe their input is being heard. Encourage the Web content volunteers to feel free to help keep parts up to date, or even delegate to them parts that they like. (If you delegate something to a volunteer, be serious about the delegation. Consider that person the "owner" and ask them first before you do anything to those parts.)

Keep the SVLUG meeting pages up to date.

Keep the pages that refer to meetings up to date, whenever the Meeting Speaker Coordinator tells us what has been arranged for future meetings. (Bug him/her for info, when he/she forgets to tell us. Specifically....

• After each meeting, update the Meetings page, so that it has the date of the next meeting. If you don't know the speaker or subject, remove them from the page heading.

• After each meeting, update the PreviousMeetings page to include a description of the meeting, the location, the attendance, and any other notes that were significant about it.

• After each meeting, update the events.html file that is referenced from the Web site's front page via include directive, to update the meeting date, speaker, and topic. (Put "TBA" until these things are known.)

• Once a meeting speaker is announced, update the svlug-news.txt file to include news about the meeting, and run "/home/httpd/bin/mk_live_links svlug_news" to deploy you change. Use other news entries as a model if you need to. (Make the title a one-liner summary. Set the expiration date to the day of the meeting, so it will disappear from the home page at midnight, even if we're all at the restaurant at the time. )

• Also, once a meeting speaker is announced, update the Meetings page, so that the heading includes lines with the speaker's name and the topic. Update the table of meetings to include that meeting and speaker. (Or replace the "TBA" if that was already there.)

• Once a month, you'll also want to update the upcoming-dates list on the Installfests page. Last, after Hacking Society meetings, update the HackSoc page.

How do we make major changes to the site?

Major changes that add on to or change the look of the site should be decided by consensus, led by the Web Content Coordinator. Any volunteer may make a suggestion or even prototype page/layout/etc., but don't install them before others can review them: Expect to make changes to accomodate others' suggestions. If you get suggestions that are in conflict, go ahead and make a suggestion, but let the Web Content Coordinator resolve it, especially if the conflicting suggestions come from other SVLUG officers.

Remember to use the header and footer include files.

Note that we've got a lot of server-side includes (SSI), so you only need to change header.shtml and footer.shtml to change the headers and footers of all the pages. Be sure to use SSIs on any new pages, so that can be continued in the future.

Use the Revision Control System (RCS).

We use RCS for revision control, so you can be fairly generous in letting others who have SVLUG accounts just make modifications to pages: If something needs to be backed out, it can be done. Some pages that haven't been modified in a long time are not (yet) under RCS: When you need to change one, check it into RCS, first.

• To check out a file prior to editing:
  co -l filename To check in a file after editing:
  ci -u filename Use a meaningful but brief description of the changes that were made.

A cron job will complain to the Web Team (reaching the Volunteers list-members) every 6 hours, if an RCS-controlled file is left locked for more than 8 hours. So, remember to check them in, when you're done editing.

Web Team members need to be in the "webslave" group.

Anyone authorized for Web content maintenance needs to be added to the "webslave" group. This group was named back when it was just Chris and Rob on the server -- it was supposed to be an inside joke for what they called themselves, so don't let the name bother you. We like humour, so we're not changing the name.

What's up with the directory and file write permissions?

You will find that all the directories are group-writable by "webslave". Though many files are not writable at all. That's normal -- RCS turns off write permissions on checked-in files. It'll become owned / writable by you when you check it out.

Establishing RCS control on a file

If you want to create a new file or modify a file that is not under RCS control, check it in first, in order to establish exist. Then use the usual "ci -u filename" method to check in the file. RCS will prompt you for a description of the file: Use the title if no other one-liner description comes to mind. RCS will not prompt you for a revision comment, because the first revision's comment is always "initial revision".

How do we handle grey areas between software and content?

When there's something that is both content and software, at least the Web Content and Web Software Coordinators, if not the whole team, should talk or e-mail about it.

Web Software Tasks and Procedures

• Web Software volunteers may write and install CGIs and mod_perl scripts.
• Do anything that's necessary, but don't waste CPU. We have only an old PIII/512MB, until something bigger gets donated. Even its 486 predecessor demonstrated no difficulty handling 30000+ hits per day. We survived the dreaded "Slashdot Effect" during international media coverage of the "Great Linux Revolt", "Launch Win98 on a Rocket", "Future of Linux", and "Silicon Valley Tea Party" events. But one poorly-designed program can bring any server to its knees, so be careful with what you write and install.
• Notify the Web Software Coordinator, either prior to or upon installation of a CGI (but always prior to advertising its existence), so it can be reviewed for performance and security.
• Notify the Web Software Coordinator prior to installation of a mod_perl script, so it can be reviewed for performance, security, and API conformance.
• Changes to the Apache HTTPD configuration should usually be brought to the Web Software Coordinator or the Web Team, first. The exception is emergencies, when any action may be taken to resolve the emergency, and an explanation / summary must then be submitted afterward.

Web Software Resources

• The Web server is Apache 1.3 with mod_perl. We had a local copy of the manual on the pure-HTML site at http://www.svlug.org/sw/apache/, but may or may not take the trouble of loading that into the wiki.

• These files (which are all in the fetch/ directory, to keep them separate from the manually-maintained files) are automatically updated by cron jobs.

The Perl5 WebFetch module and documentation can be found on this site. (Perl5's WebFetch module was created by SVLUG.)

You can recognize the output files by these lines in them:
<!--- begin text generated by Perl5 WebFetch 0.05 - do not manually edit --->
<!--- end text generated by Perl5 WebFetch 0.05 - do not manually edit --->

• You can add to the SVLUG News on the home page and the news page at once by editing (including RCS check-out/check-in) svlug-news.txt. It has comments with the file format. Add new items at the end. Use an expiration date if you want it to disappear from the home page after a certain date -- it will not expire from the News page. Then you can leave it, and a cron job will pick it up within 20 minutes. (2005 addition: This cronjob is currently broken.) Or run "/home/httpd/bin/mk_live_links svlug_news" to force an update of both pages immediately. Try not to force an update at the same time as the cron job, which is 2, 22 and 42 after each hour.

• We have a severely underused voting booth at http://www.svlug.org/cgi-bin/stv This program can be configured for multiple-preference types of votes. It does some pretty sophisticated "Single Transferable Vote" computations to figure out the highest preference, after each voter submits a list of highest to lowest preference. Ask Ian to set it up, if you want any kind of preference poll.

Standards, Nits, Peeves

Stuff submitted for SVLUG's site tends to suffer questionable grammar, spelling, punctuation, idiom, and markup. As Web Team staff, you're not just entitled to fix those; it's part of the job. Here are some of the most frequent gaffes, and some site conventions to enforce:

Singular possessives of nouns: Form the possessive of a singular noun by adding apostrophe followed by "s", even if the word already ends in "s". Why? Because ending a word with "s"+apostrophe is reserved for something different: denoting plural possessive. Thus, for any singular noun, even if it ends in "s", form the possessive by adding apostrophe+"s": "Charles's wife", not "Charles' wife". We don't care that the S.F. Chronicle and S.J. Mercury-News violate this rule every day to shave a letter from certain headline words: Omitting the "s" on singular possessives remains illiterate, no matter how widespread the error.

"Hopefully": I'm speculating hopefully (that is, in a manner full of hope) that you'll be able to spot an author sprinkling this word around without any clear referent, and substitute what he/she really means, which is "I hope that...".

web: Used for spiders' threads or fabric patterns, it's a common noun, and so can properly remain lower-case. However, if (as usual) it's short for World-Wide Web, then it's a proper noun and needs correction to "Web".

website/Website: No such word. Correct to "Web site".

No, there's nothing wrong with inventing new words, especially where they make our language more expressive and fill a need not met by existing words. This one doesn't qualify, and is really just the result of people being sloppy. Some would call our cleaning it and similar things off our pages "prescriptivism"; I prefer the term "leadership".

Physical HTML tags, where logical tags are needed: Practically all instances of the HTML "i" (italic), "b" (bold), "u" (underline), and "tt" (typewriter text) physical-styling aka presentation-markup tags are erroneous usages by people who've made the classic bonehead error of thinking they can dictate user output-device presentation via the Web, and that they should try to do so. The fact that this is unclear on how the Web actually works has been known since the Web's earliest days. You should therefore substitute "em" and "strong" (logical-styling aka semantic markup tags) for all instances of "i" and "b" (respectively), except where the author is literally talking about italics or bolding.

Sentences inside other sentences: You'll find authors jamming parentheses around sentences and then stashing them within other sentences. Yank those back out: Each complete sentence must stand on its own.

Quotation marks should enclose only what's actually being quoted: To avoid ambiguity and impose a bit of logic onto the English language, we depart from a traditional punctuation convention that reportedly harks back to mechanical problems with lead type: On our Web site, closing punctuation should go inside quotation marks only if it's being quoted. Otherwise, not.

Ellipses consist of three dots (not two, not four). A fourth dot is required where there should be a period. (It is the period.)

Which vs. that: Nine out of ten "which" uses (to introduce a relative clause) are in error. The tipoff is when there's no comma before "which": The author meant "that". (One uses "that" for clauses that further specify what's being referred to, "which" for parenthetical clauses that don't further specify. No comma strongly implies intent to specify, not just comment.)

The word "they/them/their" is plural: Attempting to kludge a gender-neutral singular pronoun onto English by using "they" doesn't work, because it already means third-person plural. (This remains true no matter how many 500-year old contrary examples people find, no matter how many modern examples they find, and no matter how common the error is when you, I, or anyone else speaks -- all of which merely prove that shoddy work pops up all over.) There is no good solution to the overall problem, but destroying the distinction between singular and plural (e.g., by using "they" as a singular pronoun) is not OK. Rewrite as necessary to fix.

Sex vs. gender: While we're at it, we should mention the common error of referring to "gender" when the speaker means "sex" (probably out of squeamish avoidance of the latter word). These are quite different concepts, gender-based distinctions being those of socially constructed psychology (e.g., feminine vs. masculine vs. berdache, etc.) whereas sex-based distinctions involve chromosomes and other biological plumbing. So, it makes no sense to talk about "gender discrimination" unless one means, e.g., barring both sexes from wearing skirts.

(No, thank heavens, that doesn't come up often on a technical Web site, but faint recollection suggests it has come up at least once.)

Be consistent: We're pretty informal, so, e.g., it's OK to either omit ending periods from all items in an unordered list, or include ending periods on all: Just pick a convention and stick to it. An eccentric usage might be only only slightly distracting if used consistently, but will become very distracting if it comes and goes.

Upcoming events announcements are SVLUG speaking, not the presenters: Upcoming presenters (or their PR departments) will often send boilerplate text for our Meetings page, written in the first person. One problem: SVLUG's pages about upcoming speakers are not the presenters speaking, but rather SVLUG itself. So, you'll need to re-cast this stuff, before posting it.

Resist the urge to educate people on these matters: It usually doesn't work, gets their backs up, and isn't worth the ill feelings. Just, please, fix it without comment, thereby making both SVLUG and the authors look good.

Wiki Addendum

We favour initial capital letters for page names and directory names, and also favour plurals. Thus, Directions/Cisco/BldgJ and Policies/Jobs.