v1.1 / 11 Jul 95
This pages is for folks contributing material to the JIS Help Pages. We're interested in something along the lines of a FAQ or How-To document (either as HTML pages or plaintext), as well as "unedited" contributions of short comments or corrections, culled posts, and so forth.
You may ask, "Why does the JIS need local copies of help pages anyway? Why not just let folks create pages at their home machines and have the JIS provide links to them?"
It is essentially a control issue: control of content, style, and quality. By filtering the help pages (and other JIS material) through a few individuals, we can provide these controls -- to keep the pages structured and formatted somewhat similarly, to make it easy to update and keep track of the contributed pages, to assure certain technical properties (e.g., HTML portability and relative links), to assure authors get credit for their work, and so on. In this document, therefore, we are attempting to present some basic guidelines covering a few simple issues in creating pages to go into the JIS help pages.
Furthermore, Barry's goal (which I obviously share) is that the JIS site itself should contain -- locally -- as much juggling-related information as we can get. This is for two main reasons: local JIS accesses will be in general faster, and "private" pages tend to move or disappear, while the JIS won't.
However, it's worth noting that there are some pages that we don't want to provide locally:
Note that although we don't want local copies of some things, like a page on the history of mime, we will usually be happy to include a pointer to it, if it fits somewhere.
It is very important to me that folks get credit for their ideas and words.
Please put your name somewhere on each page you create.
If incorporating someone else's post or suggestion, please give them credit. For a minor contribution, you may wish to have a "thanks" or "acknowledgements" section; for more substantial contributions, it's better to credit them where the material appears. Include the contributor's email address where possible.
I always try to get the permission of credited individuals: I ask if I may use their name, and request an email address and home page. I have a form-letter which I send, and, to date, everyone has responded positively saying it's okay to use their name and include on the JIS anything they've contributed. In the case of posts to r.j, the text of the post is in some sense on the public domain -- nonetheless, if someone ever objected I would not use the material.
If you do nothing else, please put a version number and date on each file you create; for HTML files, these should be in comments t the top of the pages, as well as somewhere in the document. If submitting multiple files which together make up one logical document, the whole document should have a version number as well.
"Spelling counts. Please spell-check your files."
That having been said, I'll admit right off I never remember to do this. This is inexcusable, as in my daily life I'm obsessive about typos and grammatical errors in the papers I read and write. Nonetheless, I have an excuse: spell-checking the help pages are a pain because (1) they're html documents, (2) there's lots of grungy stuff like email addresses, and (3) r.j posts tend to use words that don't appear in dictionaries. In the case of (3), some are legitimate misspellings, while others are deliberate manglings of the English language that I wish to preserve -- for example, see any post by Tarim.
It's worth noting that the only complaints I've ever gotten about the JIS had to do with poor spelling. On both occasions the flames were so rude that I think they turned me sour on the whole subject.
Some people like to explicitly copyright their work, by using a "(C)" mark or by including text of the form "this text is copyright 1995 by..." Some like to include a disclaimer as well. I perfectly understand the desire to do this. I have had my own work used without attribution in other individuals' published documents (not JIS-related), and it really ticks me off.
Nonetheless, I have not included any explicit "(C)" notes, in part because I think they look ugly and in part because I dread the idea of doing this to each of the pages. For the most part, however, I'm not sure it would be legally meaningful -- especially on a document like the help pages, which rely on others' texts.
Many months ago, someone approached me about using the JIS Help Pages as source material for a book on juggling. I said I would not cooperate with such an effort -- I don't believe many of the original authors of the help pages' material would give consent to publication in any for-profit form, and I think it goes against the spirit of what we're trying to accomplish with the JIS. For copyright reasons, it may not even be legal. Had the would-be book author decided to go ahead without my help, though, I'm not sure what I would have or could have done.
So, should you included copyright notices? Your decision. Should you include disclaimers? Again, your decision.
One of my long-term goals is to read up on this subject and decide what to do. Several good copyright FAQs exist, and the subject of print publication of FAQ material has been covered before.
Here we discuss issues relating to those submitting HTML documents to me.
One the one hand, I'd like to keep your documents looking like mine, but on the other hand, I don't want to edit your files in any nontrivial way. I already have some effort invested in infrastructure that uses m4 macros to automatically generate menus, turn names into email addresses, and so forth -- but the system really isn't designed for anyone else to use. Hopefully, the guidelines below will keep your pages looking and feeling like mine.
There are numerous style guides on the Web for authors of HTML documents (if you have a favorite, please let me know). It might be worth your time to read some, if you haven't already. For the most part, particular technical style issues are dealt with later in this section. Here we discuss some important, nontechnical style guidelines. (I admit to violating all of these rules here and there; mea culpa.)
Bad: "Click <a href="foo.html">here</a> for information on juggling."
Better: "More information on <a href="bar.html">juggling</a> is available."
(More guidelines as I think of them. Suggestions welcome.)
Always, always use local paths -- this will allow Barry to set up mirror sites of the JIS someday. Examples:
No: http://www.juggling.org/help/siteswap/faq.html
No: /jis/help/siteswap/faq.html
Yes: ../siteswap/faq.html
Yes: /books/lasso/index.html
The help pages all reside under top level "help" directory, and your paths should act accordingly.
Yes, the local-only rule will make development of your own pages difficult. Since I maintain all the JIS help pages on my machine at home (Barry mirrors me :-) my strategy is to stub in empty files for all the JIS pages I reference outside the help directory. That way, I can still verify each link is to a valid file.
If your FAQ spans multiple pages, that's okay -- minor hassle for me, but no big deal. In some cases it is more appropriate to have one large page with intradocument links ("#section").
In the "main" page, please include (in comments) the names of the other files that make up your document.
If you're doing something big and have to use subdirectories, that's okay too -- again, though, please include a "table of contents" for the files in comments in the main document.
The help pages are designed to be menu-based and very tree-structured. I think this makes navigation much more intuitive, and encourage you to follow the pattern of the rest of the help pages.
For consistency, I suggest you try to use menus similar to the way I do. (The little balls are color-coded deliberately, as explained in the help pages introduction.) Every subdirectory must have an "index.html" file -- generally, the menu should go here.
Gifs are good, we like gifs. Use them freely. Please keep them all in a subdirectory, though, just to be neat and tidy. (No, your gif directory should not have an index.html file. Thanks for asking though, shows you're paying attention.) Big gifs should not be inlined.
To use an Official JIS Icon, such as the colored balls, use a relative path to get to the icon dir ("/Icons").
I use macros to expand folks' names into links -- you'll have to do it by hand. The first time it is used, a full name should be a link. Subsequent uses of the name (in the same local area of the file, anyway) need not be a link -- too many links make things look cluttered.
The method I use to translate names to links follows these rules:
Uses of email addresses should always expand to "mailto:" links.
Please use all the "document" tags -- <html>, <body>, etc.
I use "end-tags" even when optional, but that's because I'm obsessive -- for example, I always enclose all my paragraphs with <p>...</p>. You can be somewhat looser, if you wish -- but please don't break the HTML rules about what goes where: an ordered list tag (<ol>) should not end with an unordered list end tag (<ul>), don't use <p> where you really mean <br> and vice versa, etc. Lots of HTML manuals are around; spend some time getting to know the conventions.
Note: the better browsers will often display "incorrect" documents correctly, so you have to be careful (see below, Syntax Checking).
If you have access to an HTML syntax checker (aka a "lint" tool), please use it. If you have access to a tool that verifies links in a multipage document, use it too.
I use weblint. It misses some things, but gets the essentials. It is just one perl script, so is very easy to use (but slow).
I have tried htmlchek. Its checks are more strict than weblint's, but it is considerably less easy to use. htmlchek can build dependence graphs to make that sure each file in a tree is referenced at least one, that each link is valid, etc. I've got some perl scripts that do this for me (but not well); I'd prefer to use htmlchek for this, but didn't make it over the learning curve.
The JIS help pages do not currently use "back to main page" links. While most browsers nowadays have "previous page" functions built-in, this doesn't help when you've jumped directly into the middle of the help pages.
At some point, I intend to start inserting (small, unobtrusive) links to each page's local menu.
For now, you should do what you think is best.
(to be written)