Web Machinist
Table of Contents
Introduction
Structure and Layout
Writing Content
Appearance
Links
Source File Formatting
Vital Information
To-Do List
Conclusion
Introduction
The groundwork for this website and this guide was laid in the 2004-2005 school year by Finlandian Nathan Schneider. So far as we know, there was only one previous incarnation of the BACH webiste; it is available in our archives here. The present site was part of a larger project inaugurated that year called the Master Plan, which was aimed at fostering a stronger relationship between current BACH and alumni, both for purposes of sharing wisdom and securing a more stable financial base. Above all, a BACH website should embody the vision of community that is central to the organization to begin with. Our hope is that the more practical goals will follow from this one.
Someone who takes on this job should already have at least some knowledge of HTML and related web technologies. Dexterity with UNIX, ftp, and ssh helps as well. Many of these, as well, can be easily learnt with a few well-aimed Google searches and reading the source code. This job should be approached as much as a learning experience as anything. By no means must the mechanist be an expert. It was not created by one, particularly. But it was created consciously, and a certain degree of handiness, as well as nurturing love, is necessary to maintain it that way.
This site was designed with several odd philosophical principles at heart, which sometimes results in peculiar practices. I hope that anybody who works to maintain it will at least try to recognize and appreciate their value. The website is to serve as a permanent archive for BACH. It is more than a pretty front for a powerful corporation; it is a collective memory for a group of students with too much on their mind most of the time to remember. In order to serve as such, the site must maintain cleanliness and clarity so that it can be easily navigated and maintained. Comment wherever you can in your code and structure the source files as neatly as possible.
Simplicity must also be maintained. In the world of the wild web, standards and technologies are always changing. I have tried to base the BACH page on stable HTML 4.0 and CSS standards that work well on even older browsers, and hopefully those of the future as well. Funny technologies like JavaScript should be avoided. Also, I encourage you to do all your coding by hand in a text editor, the old fashioned way. Well-written HTML code can be tremendously rewarding and far more reliable than what gets written by helper programs. Anyway, in the co-op spirit, try to use free software whenever possible in the development process.
This contributes as well to portability. The site should be able to function equally well whether accessed from a disk or a web server. To this end, the site uses no server-side includes (SSIs) and doesn't mess with such cgi scripts as other sites might rely on. Importantly, all links should be relative rather than absolute so that it can be easily moved.
Finally, consistency is important to maintaining a coherent and co-operative voice. As web mechanist, study the source code of what has already been written. If you are making a list or a page of pictures or a new page for a house, draw on similar ones that have already been done on the site. If you do decide to organize information in a different way in one place, change it elsewhere as well in a uniform way.
This site is more than a pretty face. It is a lifeblood, a tradition, and a teaching. The mother of all that is GC. The web mechanist is the electronic guardian of this mighty mantle. Treat it with care! Learn from it. Read the content and the history that you manage, tell stories to your housemates over fires in the driveway. These eternal streams of past and present rescue are all that rescue us from utter un-coperativeness and all the nonsense of the world outside our dear co-ops.
Structure and layout
A very particular structure and layout is present on almost every page on the BACH site. It is not particularly important, but it is important to be consistent. The best way to get a feel for this is to look at the existent source files. Here is a general overview of the structure of the code for every page:
Doctype statment - General necessity for HTML 4.0 code.
Head - Nothing fancy; just the css link, the title, and some
<meta> stuff if you like.
Header Table - This includes all the main links and their
pictures that are available from every page. Make sure that the
<img> and link paths are of correct "depth."
Filler and title - This is where the main table begins. Again,
make sure the <img> path is properly aligned.
Content - between the big ---------------'s in comments goes
the content for that page.
Sidebar - Here pick the picture that goes on the side of the
page. The pictures should be 72 dpi and 150 pixels in width. In
general, every section (houses, dining, about BACH, etc.) should have
its own sidebar picture common to all pages within it.
Footer - This element should be uniform on all pages. It includes
BACH contact information. Make sure this is up to date!
Writing Content
I have cultivated a particular style of writing the text content on
this page, and it is really up to you the extent that you want to
maintain it. Text is kept mostly inside <p> tags
unless there is some reason to do otherwise. The tone overall is
borrowed from the tradition of the
bachlets. It is colloquial and direct. I have conveyed the
emphasis of a speaking voice in <b> tags;
they are in turn defined in the universal css file,
/css/styles.css. Above all, the voice should be
communal and co-operative. Draw as much as you can on BACH
literature and the help of other BACHers. On the website we should
speak to the world as an affectionate body.
Appearance
The previous BACH site was designed as a jolly spoof on the Brown website, deeply indicative of BACH's odd, mocking, yet probably dependent relationship with the University in general (without Brown we'd only be ACH). The present site, instead, draws on BACH's own folk art tradition, best represented in the corpus of bachlets and related material. Though it is a creature of the digital universe, the site finds its aesthetic in the cut-and-paste simplicity of DIY publication in a now-bygone time.
Much of the artwork I have used was scanned directly from archival files, all of which are stored in the Hystory & BACHuments section. As much as you can, continue to draw on this material. Not only is it beautiful and inspiring, but it connects us visually to the easy-to-forget tradition that is BACH's ancient soul.
As it is, the general appearance is pretty set in stone and would
require some extensive find/replace work in order to fix. I certainly
would encourage you to make revisions if you like, but I'm sorry to
say that, in the interest of avoiding dynamic content, I made it
pretty difficult to do so. Easiest to change are the colors and
classes in the /css/styles.css file. Hardest are those
that are hard-coded into every single file, like table dimensions
and the header menu.
Links
Links are a powerful tool in any hypertext document. They offer the
user access to a whole world, potentially. Use links liberally to
create as interconnected a universe as possible. When something
is related to something else, connect them mutually with links. Such
wild relationships model the thick weaving of living people and living
past that make BACH life possible. For the site to function properly
and portably, links must be attended to carefully. All links
should be relative rather than absolute. This is to ensure
that they do not depend on the server or disk location where the site
is stored, but instead on their location relative to the page linked
to. Rather than links like <a
href="/fire/water.html">, use <a
href="../../fire/water.html">, where elements like
../../ refer to places in the fire hierarchy.
Because the site is supposed to be able to function independently of
a server, you have to be very explicit about the paths of your
links. With a server, it is often acceptable to simply create a link
to www.fire.com/water/, which of course will bring up the
page that is actually www.fire.com/water/index.html" or
the like. In order to work without a friendly server, though, we must
explicitly include the index.html in all cases.
External links, of course, are the exception. They are necessarily
absolute links, and they can assume that a server will receive them.
On the other hand, we cannot assume that our readers will have
the internet access to use them. Nevertheless, outside links can be a
good thing to offer from time to time. When you do use them, make sure
to put them in a new window by adding the target="_blank"
to your anchor tag.
Source File Formatting
Turnover is the essense of BACH culture. As web mechanist, you must always be aware that you are not the last and that more will come after you. The main message you leave to them, whatever state this document is in, is ultimately in the code you produce. Web browsers may not care so much what your code looks like, but future co-opers will!
There are a easy few steps to producing readable HTML. It is easy once
you get into the habit. First, use lots of comments in your
code. These begin with <!-- and end with
-->. Everything in between is invisible to the outside
world and reserved for your own reference and that of future BACHers.
Use comments to walk a reader through the elements of your documents,
especially when it is not immediately clear. They are also useful for
visually isolating parts of the page that are edited often from those
that should be left untouched.
Also, try to keep your lines of code as short as you can. About 70 characters per line is a good rule of thumb. This makes reading easier. Use lots of line breaks in logical places so that the code reads intuitively.
In all this, try to stick to HTML 4.0 standards where you can. In tags
that have only one element, such as <br /> and
<img src=".." />, use the final slash as I have
just shown. Also, keep your html commands in lower case. Practically,
HTML is case sensitive, but newer conventions are beginning to expect
lower case, along with the final slash, in conformity with XML syntax.
Vital Information
As web mechanist, there is some secret stuff that you need to
know in order to maintain the site. This includes:
- access to the server (though your Brown authID)
- login and password for the discussion board (a phpBB2 program)
- login and password for the discussion board's mySQL server
Obviously, these may be a bit too sensitive to leave lying around a
public website like this one. Be sure to get them from your predecessor!
If all else fails, you can generally ask the Brown CIS folks and
they will help you arrange access.
To-Do List
Try to keep this updated. It's a list of what should or could be done
to the site to make it better.
- Develop Wiki content that is reliable and retains archival value
- Always improve fundrasing sections
- Develop the BACH Glossary
- Make it easier for all BACHers to adjust the news section on the
main page
- Build a menu archive in the Dining
section
Conclusion
At times this document talks in terms of "I." But remember that "I" is not any particular person. "i" stands for our mighty voice! As web technician, feel free to edit and adjust it as you wish. Along with the whole page and the whole corporation, the "I" is GC. Above all, your job is to build an edifice that speaks for and embodies cooperation.
