I'm not exactly a technical writer, but I've read a lot of technical writing. Some good, even.
"Be conservative in what you do; be liberal in what you accept from others." http://en.wikipedia.org/wiki/Postel%27s_law The conservative format for URLs in documents (ca. 1993) was to start in the leftmost column, delimit the URL within angle brackets, prefix using URL or URI labels, always include the /scheme/ (e.g., the "http://"; part), include trailing slashes where no specific resource is named, and provide a line break after, e.g., <URL:http://www.nleomf.org/> Many electrons were given in service to arguing the merits of that format. Software has gotten somewhat better at discerning URLs mixed into text, but not yet to a point where it's to be relied upon, so some of those conventions are no longer as important. Starting on a new line, including the scheme, and excluding extraneous text on the same line are still best practices though. People have gotten better at seeing URLs too, but I'm still surprised when I write user instructions that are very specific about every aspect and I include an address like http://mail.example.com. People frequently assume I've omitted the "www" part, and are stumped about why http://www.mail.example.com doesn't actually work. In most other regards, I treat technical terms like foreign language terms not found in an English dictionary; italicizing them (or otherwise setting them apart) upon first use and including a definition or explanation immediately after. I've never had to write my own formal style guide or addendum because most of my writing is short and stands on its own, but that's always an option. (In this message, my preferred format is the one I used first. The conservative format is too fussy for anything outside of CS thesis work, and the inline examples are specifically NOT intended to work so the format doesn't matter as much. I also included one way of implying italics where font variants may not be available. Semantic markup, anyone?) Dave Salovesh Information Technology Manager National Law Enforcement Officers Memorial Fund 202.737.8521 (phone) | 202.737.3405 (fax) | www.nleomf.org Help Build the National Law Enforcement Museum www.LawEnforcementMuseum.org - 866.446.NLEM (446.6536) -----Original Message----- From: mcn-l-bounces at mcn.edu [mailto:[email protected]] On Behalf Of Morgan, Matt Sent: Thursday, September 25, 2008 12:50 PM To: Museum Computer Network Listserv Cc: Jennifer Boynton Subject: Re: [MCN-L] [MCN L] - Style guide for technical terms On 9/25/08 12:14 PM, "Folsom, Diana" <folsom at lacma.org> wrote: > The "period following the URL" issue is addressed in 17.10 ("URLs and > punctuation"), where they recommend including the period because: "Other > punctuation marks used following a URL will be readily perceived as > belonging to the surrounding text. It is therefore unnecessary to omit > appropriate punctuation after the URL..." > > In other words, readers will understand that the period (or comma, or > whatever) is part of the sentence, not part of the URL. Human readers will, but will their email readers or other apps? I.e., what about clickability when you're depending on some interpretation by an unknown, unthinking software application? I don't think there's a lot of standardization here, so I bet that a period can cause trouble. I always end up writing my sentences so that I can include URLs on their own lines without needing a period right there. For example, this URL: http://www.metmuseum.org/ points to the Met's splash page and artwork of the day. Semi-informal, yes, but it works for humans and machines. Putting URLs in parentheses seems to work most of the time, too, but I don't know if it works all of the time. How often do we end up cutting and pasting URLs into our web browsers, and even recommend it to users of email we send out? I don't think most people are very likely to do that very often. Clearly this is not relevant when you are writing web pages and control the HREF. In that case use a period (but you're probably not writing out URLs on web pages anyway, rather you're linking from related text). Matt _______________________________________________ You are currently subscribed to mcn-l, the listserv of the Museum Computer Network (http://www.mcn.edu) To post to this list, send messages to: mcn-l at mcn.edu To unsubscribe or change mcn-l delivery options visit: http://toronto.mediatrope.com/mailman/listinfo/mcn-l
