Tag: technical writing

Commandline Tool? Command-line Tool? Command Line Tool?

Sorry for the repetitive title, but Apache Taverna is preparing a release that will include the Taverna Commandline Tool, or is it Command Line Tool, or Command-Line Tool? Or just Command Line?  Now you see the problem. The name for the tool is different throughout the documentation. Not good.

The project lead, not a native English speaker as it turns out, requested that those of us who are native English speakers weigh in on the correct name for the tool. Challenge accepted. How hard can this be? I know compound adjectives are frequently hyphenated when they modify a noun (think, Red-headed woodpecker), but maybe there is a different software-development convention for this particular term?

First, look online

It turns out there is some inconsistency in the online use of command line tool versus command-line tool.  First, I found some examples without hyphens: What is the Command Line Tools Package? and Top 10 Command Line Tools. Then I found a different use, from Wikipedia, that was hyphenated: Command-line interface. But the article has an “issues” flag and, oh yes, it’s Wikipedia; not a good academic reference. I next found Command-Line Reference from Microsoft – with a hyphen. And then I found another from Microsoft, this time without a hyphen: Using command line tools for networking information. And finally, two more from Microsoft – with hyphens: Windows 7 command-line tools and programs and How to create a command-line toolkit for Windows. It seems like the hyphens have an edge, but I wanted a more definitive answer. Continue reading “Commandline Tool? Command-line Tool? Command Line Tool?” →

Advertisement

ASF CMS Editing Hints for New Committers

I was mesmerized by the abundance of resources for new Apache Software Foundation (ASF) committers. As a result of this bounty, it took more time than I expected to make my initial commit. The process now seems straightforward, but way back, say, 24 hours ago, things were much fuzzier.

Two resources are key. If you’ve watched Rob Weir’s video tutorial and read the Get Started Editing a Page link in the CMS Reference, good for you! You are ahead of where I was. These references are probably good enough for most people, although one important point is missing: The copy I was editing did not match the live web page. I needed to update my local version before editing, which sounds obvious now, but that’s because I finally understand how the process works. Continue reading “ASF CMS Editing Hints for New Committers” →

API Endpoints vs Resources

API Endpoints vs Resources

Aha! moments are the best. Don’t you agree? Whether it’s learning something brand new or something I didn’t know quite as well as I thought, I live for the moments when things just click.

These moments are, of course, preceded by another kind of moment: the tilt-your-head, furrow-your-brows, something’s-not-right-here moment. I recently had one of those moments reading about API endpoints and resources. Continue reading “API Endpoints vs Resources” →

Unpacking What I Know About Writing

Technical communication is a complex task. As technical writers study and hone their craft, they compress what they learn until using it becomes second nature. If you’ve never studied education, you may not even be aware of the process, but we compress knowledge every time we learn something new.

Do you think about how to move your body every time you take a step? Of course not, but learning to walk requires extreme concentration. When students learn algebra, if they haven’t compressed, or packed, their knowledge of basic operations, it will be impossible to master the new material. Packing new knowledge means we have more brainpower available for the next new task.

Unpacking happens as well. While students are compressing knowledge as they learn, teachers are unpacking knowledge to teach. Continue reading “Unpacking What I Know About Writing” →

The Odyssey Effect

AKA, the as-soon-as-you-buy-a-new-car-everyone-has-that-car effect.

Okay, I made up the Odyssey Effect*, but it turns out there is a name for that phenomenon: it’s called Baader-Meinhof phenomenon or, more scientifically, frequency illusion. And it doesn’t just apply to products. Words, songs, and even the language in job postings can trigger the feeling.

I was reminded of the “Odyssey Effect” while at a recent STC chapter meeting. A new member and I were talking about job hunting. She is stronger in tools knowledge and experience but weaker in domain knowledge, whereas I am just the opposite. When searching for jobs, she remembers all the postings requiring domain knowledge (network engineering experience, etc.), and I remember all the postings requiring FrameMaker and so on. Continue reading “The Odyssey Effect” →

Better Late Than Never

I probably should have started this blog when I began exploring technical writing as a career. But, as they say, “better late than never.”

Earlier this year I was looking for a new direction. My daughter was getting ready to graduate from high school, and I was in a position to give my full attention to something other than math tutoring and being a marching band volunteer. (You would be amazed at the number of volunteer hours required to get 300+ students in uniform and on the field!) After getting a master’s degree and teaching credential a few years ago, I had reluctantly decided classroom teaching was not for me. As passionate as I still am about teaching students they can excel at math, I had to be honest that my skills and inclination favored small groups over classrooms of 35 students. Trying to give my best to 175 students would have consumed me. Not healthy.

I struggled with the question of what to do until I realized writing was a common theme throughout my life. Continue reading “Better Late Than Never” →