| Home >> Varia >> Software Engineering

A Few Software Rules For This Web Site

Web site logo

1) Introduction

The goals of this document:

- Be a "cheat sheet" for myself, so I'll at least be consistent with myself for the organization and programming of this web site!
- Let other webmasters know how to manage this web site.
- Be general enough (especially sections 2 and 3 here below) to help other web sites.

2) General Rules

2.1) Of course, the Legal Considerations of this site have precedence over these rules!. In other words, programming presupposes Morality and Law. For example, we have to avoid hateful propaganda, avoid foul language, respect other people's intellectual property, etc. A simple way of doing this is to visibly adhere to a "Catholic Web Site Code of Ethics" (see for example #2.4, "Charter of Duties of Catholic Media", in "The Mediatic Body of Christ").

2.2) Multilingualism. Generally, if we live in an officially multilingual country, all the contents of the web site must be available in the official languages. In my case, since I'm in Canada, everything must be translated into English and French (that's the minimum! I'd love to add Latin and Spanish!). Tolerated exceptions: correspondence, reactions of people to this web site, other sites we link to, less-important documents in the "Varia" section.

2.3) No ads on the web site. Never, of any kind. See also Legal Consideration #24.

2.4) No flashing and spinning do-dads. As far as possible, text and simple images only. Modern society tries to hyperstimulate the senses and the imagination, in order to snuff out study and prayer. I want to do just the opposite!

2.5) No hyperlinks to suspicious web sites. Of course, I don't control the content of other web sites, but I must make efforts to never point toward bad sites.

2.6) No information overload. In general, web sites tend to put too much information on one page.

2.7) Usable locally. I must be able to copy the folder containing all files for the web site onto some other media (USB thumbdrive, DVD, compressed file sent by e-mail, etc.), hand it over to somebody else, and that person must be able to use the whole web site on their computer, without installing any software other than a standard web browser.

Reminder to myself to avoid excessive use of JPG files.
Reminder to myself to avoid excessive use of JPG files.
(Source)

3) More technical rules

3.1) Never change neither the names or locations of HTML files. To avoid breaking other people's hyperlinks, including those of search engines like Google.

3.2) The least possible programming complexity. Only HTML. No ASP, no PHP, no Java applets, no CMS, etc. Many reasons argue for this: ease of indexing by search engines (see #3.1 here above), reduction in maintenance costs for the web site, ease of changing webmasters, increased tendency to focus on the contents of the web site rather than the accessories (see #2.4 here above), faster page loading, site usable by antiquated computers and/or computers not connected to the Internet (see #2.7 here above), site usable by "smart telephones" and other mobile devices with small screens (see for example Google Mobile-Friendly Test to test mobile-friendliness), etc.

3.3) Web site usable in text mode. The poor don't have high-speed Internet access, and disactivate image loading. The site must be perfectly functional in text mode.

3.4) Respect the standards of www.w3.org. All the pages must pass without errors the automated validation test (HTML 4.01). (I use A Real Validator by Liam Quinn to check the whole web site in batch mode.)

3.5) Mirror site for dependability. If a web site is important, it should be "mirrored", i.e. copied entirely on another site, preferably physically in another country. Tell users about this site in the "index.htm" file in the root, and in "contact.htm".

Link rot.
[Source]

3.6) External hyperlinks. We must as far as possible use the wealth of the Internet, while minimizing broken hyperlinks (link rot). I don't know how to avoid the link rot problem. The least bad current solution is:

External hyperlinks are classified in two: the important ones, i.e. those which must be fixed when they are broken, and the others (which must still be kept, often for copyright reasons, and which even when broken can often be used to find the original document given a few efforts with Google). Moreover, all external hyperlinks must be flagged with a little icon next to the hyperlink, like this (even if this particular one isn't external but internal! It's just to show the little icon!).

(Note for myself: I've tried already to put all non-important hyperlinks on separate web pages, with a "footnote"-style pointer. What a heap of extra work! And for no result: the broken external hyperlinks remain broken. In August 2015, I went back to the old method of just sticking the external hyperlinks in the web pages.)

3.7) Fast page loading. Among others, pages should have less than 50K or so, to let them load fast.

3.8) Spell Checker. All HTML must be spell-checked by software. Of course, ideally, they are also scrutinized by professional reviewers.

3.9) Respect certain conventions on file and folder names. No uppercase, no accents, no spaces, no plural. Keep the names short. On this site, I somewhat arbitrarily decided to use only French for file and folder names. The idea is to chose a convention, then stick to it.

3.10) Respect the General template for a page and the Folder hierarchy. See below.

3.11) No junk in the despicable PDF format. People come on the web site to read information. They don't want to be told to go download some PDF monster.

3.12) No "under construction" dead-end pages. Don't pretend something is online until it's actually online!

3.13) Fixed format for internal hyperlinks. Hyperlinks that point inside a document on this site must have the format: "s" + section number + "p" + sub-section number ("p" is for "point").
For example, the hyperlink for this paragraph is "regles_site.htm#s3p13".

3.14) No EXIF metadata in ".JPG" files. I currently use Metability Software QuickFix Filemind to clean files.

3.15) Currently, don't respect all official rules for French typography. See French version for this item.

4) General template for a page

4.1) Title of page.

4.2) stylesheet.css. All pages on this site must refer to a CSS (Cascading Style Sheet), so the visual appearance of the whole web site can be controlled by touching a single file.

4.3) Header styles. Titles and sub-titles must have "Header 1, 2, or 3" styles. There must not be any paragraphs marks before or after titles (because we can changes the space below or above a title with the styles).

5) Folder hierarchy

root
	fr: content per se of the site. Contains only HTML files.
		serm: the "Lost Sermons". Articles.
			cormed: see project description.
		philo: Philosophy section.
			artic: Articles.
			manu: See project description.
		polit: Politics section.
			artic: Articles.
			prog: See project description.
		faq: Frequently Asked Questions about this web site
		(as well as anything else which doesn't fit elsewhere).
			sjj: SJJ's personal FAQ
			ajout: chronological list of modifications to this site.
			even: recurring events.
		info: Computer Science section
			artic: Articles.
			gepsys: new programming language (English side only).
				testament: "Marketing" material.
		esd: Mr. Bachelor's Little Kit.
			artic: Articles.
			list: Lists of objects for Kit.
		livre: a few digitized books (Almost only on the French side).
	fig: the figures, graphics, zipped files, executable files, MP3, etc.
	Repeat here the same hierarchy as for "en" and "fr", but putting only non-
	HTML files. I repeat: outsite "fig", there should only be HTML files! This
	makes it easier to quickly upload modified content, without the images.
	Also, put the figures only on the French side, except when there needs
	to be one version per language (e.g. a image with a caption that must be
	translated). Try to avoid putting comments on graphics (since they would
	have to be in one language or other), but only letters which can be
	explained in a legend in an HTML file. Also, if an article has more than
	two images associated with it, make a folder with the same name as the
	article file, and put all its images in it, numbered from "01" up.
	en: ideally, the same contents as "fr", but in English.
	lt: same comment as for "en", but for Latin.
	corr: correspondance with people (not sorted by language).
	chp: web site for Christian Heritage Party EDA for Louis-Hébert.
		Don't move it because www.chp-quebec.ca points to it.
	pvq: web site for Quebec Pro-Life ("Pro-Vie Québec").
		Don't move it because www.proviequebec.ca points to it.
	anima: web site for "À L'école de Marie-Immaculée"

6) Correspondence

Quantity-wise, my web site contains a lot of correspondence. Why? (1) I feel forced to answer because of [1P 3:15]; (2) Legal Consideration #10 grants readers a right of rebuttal; (3) the prevalence of philosophical and theological errors detectable in e-mails is a factor in my prioritization algorithm; (4) I'm lazy, and e-mails that attack the Church or me are often an excellent source of motivation to make me write; (5) many web sites these days have a "Comment" section after each article, but I don't like them, so I need another way to let readers express themselves.

How should this correspondence be done? See How To Write A Good E-Mail, and the following rules:

6.1) By default, obtain permission before posting any personal information. But this rule is not absolute (See Legal Consideration #2).

6.2) Verbatim. E-mails received must be posted as far as possible with a plain "copy-paste" (including the header indicating sender, receiver, timestamp, etc.), to preserve an accurate record. The only exception is minor formatting (rearranging line breaks, removing HTML, encoding e-addresses, replacing unprintable words sent by [deleted expletive] twits, etc.).

6.3) No Third Quote Level. The "first quote level" is whatever is written by the sender or me. The second quote level is whatever is prefixed with ">>". I may not use third and subsequent levels of quoting. When you say that I said that you said this or that, I get confused. And if I can't understand something, I shouldn't say it.

6.4) English mistakes. I must not correct English mistakes in e-mails received. But in my e-mails, even if I'm quoting what was sent, I have to be impeccable.

| Home >> Varia >> Software Engineering