‘Login’ or ‘log in’? One word or two? It’s an oft-debated question. I’m not proposing a hard-and-fast rule, though I do have my preferences. What this post offers is a handy way of choosing between one word and two, if it’s important to you.
It’s not just logging in that’s affected. There are plenty more cases where we need to choose one word or two:
- ‘logon’ or ‘log on’
- ‘logout’ or ‘log out’
- ‘signup’ or ‘sign up’
- ‘shutdown’ or ‘shut down’
- ‘backup’ or ‘back up’
- ‘setup’ or ‘set up’
- and more, including words not related to computing, such as ‘workout’ versus ‘work out’
Who’s up for an experiment?
Warning: Don’t try this at home, unless your partner is in a good mood.
Try speaking these sentences out loud, replacing ‘bbbbbbb’ with ‘backup’ and ignoring the spelling for now:
- What is your bbbbbbb strategy?
- When did you last bbbbbbb your data?
- When did you last do a bbbbbbb?
Now try these, replacing ‘llllllll’ with ‘login’:
- What are your llllllll details?
- Where can I llllllll to the bank’s website?
- My llllllll failed.
Did you notice any pattern in the way you pronounced the words “back/up” and “log/in”? If you’re like me, your stress pattern in the middle sentences would be different from the first and third sentences.
- In the middle sentence, you would give equal emphasis to both parts of the phrase: back up; log in.
- In the first and third sentences, you would give greater emphasis to the first part of the phrase: backup; login.
And the answer is…
‘Backup’ or ‘back up’:
- What is your backup strategy?
- When did you last back up your data?
- When did you last do a backup?
‘Login’ or ‘log in’:
- What are your login details?
- Where can I log in to the bank’s website?
- My login failed.
Rules and things
It may be that you decide to go with the growing common usage, and just use one word (like ‘login’) for everything. But if you want to follow the ‘rules’, they’re something like this:
- If it’s a verb, use two words.
- If it’s a noun, including cases when the noun is used to qualify another noun, use one word.
What about hyphens (‘-’)? Technical writers try to avoid them.
Who decreed that this is how it’s done, and where is it written down? Most tech writers and other guardians of language would agree that we should be descriptive rather than prescriptive, and that there are a equally-viable alternatives out there. But we also agree that it’s good to have a standard, so that our readers have a smooth ride through the documentation and application screens.
Here are some style guides and commentaries that agree we use one word for a noun, two for a verb:
- Guardian and Observer Style Guide – Scroll down to the entries for ‘log in’ and ‘login’.
- Apple Style Guide – See the entry for ‘log in (v.), login (n., adj.), log out (v.), logout (n., adj.)‘, on page 96.
- Log in vs. login by Grammarist – This post has some useful examples from online newspapers.
- A thread on the English Language and Usage Stack Exchange – People express various opinions, but the consensus is one word for a noun, two for a verb.
- Another thread on the English Language and Usage Stack Exchange – This one is particularly cool, because someone pointed out in a comment that the instructions on the Stack Exchange page itself said ‘Sign up or login’, and Stack Exchange fixed it!
- The Wikipedia page on login – The page consistently uses ‘login’ as a noun and ‘log in’ as a verb. It also states, ‘The noun login comes from the verb (to) log in‘.
- And someone who has a strong opinion, backed up by good research: “Login” is not a verb.
Who cares? Is this a difference between US and British usage? I don’t think so. It’s more a difference between people who feel a sense of jarring disconnect when someone uses ‘login’ and the like as a verb, and people who don’t. If you do want to differentiate, the pronunciation test may be the quickest way to decide whether you need one word or two.
There’s only one word for this spider: Eek!
This spider took up residence between my window panels for a while. It’s a huntsman: huge, very fast, scary but beautiful, and largely harmless. I put the peg there for scale. It’s a large peg.
I’m composing my proceedings paper for STC Summit 2014. Not all conferences require a proceedings paper. This set me wondering: Do people find proceedings papers useful? Do you read them, either during or after the conference, or perhaps not at all?
The “proceedings” of a conference is a collection of papers written by conference speakers. The content of a proceedings paper may be a summary of the talk, or an academic treatment of the topic of the talk, or a deep dive into one aspect of the talk.
My upcoming presentation at STC Summit 2014 is API Technical Writing: What, Why and How. For the proceedings paper, I’ve decided to write a deep-dive description of APIs. In the live session at the conference, I’ll cover the same content in less depth, then focus on examples of APIs and on their documentation, and on the role of the technical writer.
Some conferences ask speakers to present their slides a couple of months ahead of the conference date, so that the slides can be included in the documentation handed out to attendees. Others, like STC Summit, ask for a proceedings paper ahead of time, and the slides much closer to the date of the event.
When attending a conference session, I sometimes follow along on the slides if they’re part of the conference package. This is helpful if I can’t see the screen too well, or if I want to make notes on the slides. It’s very seldom that I refer to the conference proceedings. I think I’ve only done that once or twice throughout the years, and it’s been when I want an in depth look into the topic of a particularly interesting session.
What do you think? Are proceedings papers useful, how do you use them, and do you prefer the slides, the papers, or both?
I’m in the throes of composition. My presentation for STC Summit 2014 is in good shape, and I’m working on the proceedings paper right now. I got to thinking about why I put myself up for speaking at conferences. It’s a lot of work! Is it worth it? I also saw a post from Neal Kaplan, who doesn’t get conferences. So I decided to blog my thoughts.
If you’d told me five years ago that you’d seen me speaking at a conference, my reaction would have been
Ha ha, nope, that must have been some other Sarah.
Public speaking scared me to death. (Actually, it still does.) I never thought I’d be able to do it. Simply standing in front of a handful of peers turned me into a blob of jelly on a roller coaster.
Then Joe Welinske asked me to speak at WritersUA in Seattle in 2009. Of course, I said “Eek, no.” But Joe’s sweet persistence persuaded me to think about it. After all, he said, I knew a lot about what was then an emerging technology for technical writing: wikis. A few days later, Joe asked me again. To my utter horror, I said yes. My thinking went along these lines: I know no-one in the US. I’ve never even been to the US. If I make a total fool of myself, it doesn’t matter. No-one I know will ever know. :D
I survived WritersUA 2009. And now, five years later, I’ve spoken at twelve conferences.
Oft-discussed benefits of attending conferences include:
- Peers: Meeting other tech writers has been hugely rewarding. It’s especially great to meet in person the people I’ve bumped into on blogs, Twitter, and other online meeting spots.
- Learning: Conferences seed ideas. I see what other people are up to, get a glimpse of new technologies, peer at different products. A while later, an idea pops up about something I can use in my own environment.
What’s the benefit of speaking yourself?
Getting funding to attend the conference is a big one. For me, living in Australia, the travel costs are too big to cover personally.
But for me, the biggie is this: Putting together a presentation makes me think about how others see what I’m doing. It makes me look at my own work, and that of my team, in a new light. It gives me a wider perspective. It firms up my own opinions on what are good procedures to follow, and what could do with tweaking.
So, a call to all conference speakers: why do you do it? :)
I’m curious to see how things have changed since I last asked this question, back in March 2012: What’s your favourite API documentation, and why?
Part of the reason for asking is that I’ll soon present a session at STC Summit 2014 on API technical writing. I want to give examples of excellent documentation. I have some favourite documentation sets myself, but it’s great to get the opinions of developers and other technical writers too.
So, have at it! :) Please comment on this post.
What’s your favourite API documentation, and why?
I’ll also collect any suggestions that people send via Twitter, Google+, and other channels, and add the links to this post.
OT: This has to be the world’s best bird. Well, it’s my current favourite anyway. This is a Tawny Frogmouth, spotted on an early morning walk. Tawny Frogmouths are night birds, about the size of a large owl (34-52 centimetres). During the day, they pretend to be old tree branches.
I’ll be speaking about API technical writing at STC Summit 2014. Part of the presentation is about useful tools for API technical writers. Since there are already some great resources on the Web about editors and IDEs, I plan to focus on a motley collection of “other” tools. Those that do a specific job very well. Those of which you’d say, “When I need it, I really need it.”
There are plenty of blog posts and articles about tools for documentation and code, including open source tools. Particularly when talking about editors and IDEs (Integrated Development Environments) most people have their favourites. The debates about which tool is best can get quite fiery!
Here are some useful links:
- Mike McCallister’s presentation, Open Source Tools for User Assistance. It’s well worth following Mike’s blog too.
- Chantel Brathwaite, writing on the TechWhirl blog about Technical Writing on a Shoestring.
- From Bret McGowen on the Rackspace blog, My Text Editor Final Four.
So, aren’t you going to talk about editors at all? ;)
My favourite IDE is Eclipse. I like to dabble in Android Studio and IntelliJ IDEA, just to see what’s happening.
Now that’s out of the way, let’s look at some super-useful and less-talked-about tools for API tech writers in particular.
Syntax highlighter for code samples
I frequently need to add a code sample to an HTML page, or include a slice of code in a presentation. Code is much easier to understand if the text is highlighted to indicate method names, variable declarations, and other syntactical essentials. And it just looks prettier too.
hilite.me converts a code snippet into styled HTML, which you can copy and paste into your page. Paste in your code, and select the coding language, to get the appropriate highlighting. Then click “Highlight!” to see the result. You can grab the HTML and CSS code, or copy and paste the highlighted text itself. You can even choose from a number of styles, such as “colorful”, “friendly”, “fruity”, and so on.
For example, I pasted in a Java “hello world” class, and asked for “tango” style highlighting. The “Preview” box at the bottom of this screenshot shows the result:
Testing web services and REST APIs
There’s an add-on for Chrome browser, called the Advanced REST Client, which I find very useful for getting examples of web service requests and responses. You can craft an HTTP request, then submit the request and see the response. This is a nice GUI alternative to a command-line tool like cURL.
Let’s say I want to use the Google Geocoding API to get a human-readable address for a pair of latitude/longitude coordinates. My URL would look like this:
I’ve pasted the above URL into the Advanced REST Client tab in Chrome, then used the add-on to expand the URL parameters, making it easy to see the composition of the HTTP request:
Now press the “Send” button to see the response. This is a partial screenshot:
Very handy indeed.
Chrome Developer Tools
The Chrome Developer Tools are a little tricky to grok, but once you’ve figured out what’s going on, they’re coolth personified. To find them, click the three-barred icon at top right of the Chrome window (the tooltip says “Customize and control Google Chrome”) then choose “Tools” > “Developer Tools”. The keyboard shortcut is Ctrl+Shift+I or Cmd+Shift+I.
A panel opens at the bottom of the page. It’s pretty busy, so take your time getting used to it. You can click an option to undock the panel and see it as a separate window, if you prefer that. In this screenshot, the DevTools panel is open at the bottom of the screen, and is showing the “Elements” tab:
There are many many things you can do with the DevTools. The Chrome DevTools documentation is a good guide. These are the functions I use most often:
- Check which CSS style is in effect on a particular block of HTML. This is particularly useful when there are a number of stylesheets at play. Sometimes the cascading effect of CSS doesn’t seem to follow the laws of gravity!
- Watch the error messages scrolling past on the “Console” tab. :)
- Edit HTML on the spot, to see the effect live on a web page before putting my changes into the source code.
Open Device Labs – Access to real devices and platforms for test-driving an app
It can be very difficult to try out an application on every supported device or platform. Especially for those of us dealing with mobile apps, there are just way too many devices out there for it to be feasible to have an example of each one.
One solution is to use emulators. But here’s an exciting initiative that I heard about recently: Open Device Labs.
The idea is that people may have last year’s mobile phone lying around, that they’d be willing to allow other people to use for testing. Some people may even want to donate new devices to the cause. Smart, enthusiastic people have set up hubs of Internet-connected devices at various locations around the world, and made them available to us all to use. For free!
I haven’t yet used a device from one of these labs, but the idea is awesome. What a great way to test an app, get screenshots, figure out the “how to” instructions you need to write, and just see how the user experience feels.
Mobile emulator in Chrome browser
With Chrome’s mobile emulation, you can make your desktop browser pretend that it’s something else. It can masquerade as an iPhone, Kindle, Blackberry, Nexus, and more. This is very useful for taking screenshots, and for seeing how responsive an app is to different device sizes and resolutions. The emulator is available via a fairly obscure setting in the Chrome Developer Tools panel.
Online source repositories are good for sharing code. In a tutorial, it works well to include code snippets and point readers to the complete source in a repo. Bitbucket and GitHub are very popular. I have accounts on both, because I’ve worked with teams on both. GitHub works with Git, while Bitbucket supports both Git and Mercurial.
That’s my list so far. If I find any more tools before the STC Summit in May, I’ll add them to the list I’m creating for my presentation. It will be fun to share them with the tech writers at the conference. Can you think of any super-useful tools to add to the list?