I’ve decided that I need to learn JavaScript because I’m tired of having to ask other developers for help with something that I feel I should know. Additionally, a number of my clients have asked me to do more than just build help for them so I need to know more. And finally, I firmly believe that I have to keep learning all the time.

Thus, the effort to learn JavaScript.

I actually started to learn JavaScript several months ago when I began a new help project and wanted to do some fancy image changes on the Welcome page. It frustrated me that I couldn’t do what I wanted so I ordered HeadStart JavaScript. I’d had experience with HeadStart HTML & CSS. I can’t say I learned HTML and CSS via the book – but it’s been helpful when I need to refresh my memory on something. So, I got the JavaScript book from the same line of books.

I can’t say it was a rousing success. I don’t think the book was at fault…I think it was me. I don’t know that I was ready to take on a completely new language. So I put the book away and focused on other things, like my client work, the holidays, more client work. And now it’s the new year and I have some time to commit to something….and it might as well be JavaScript.

So, instead of pulling out the book, I decided to try out Codecademy. I’d heard about it from some colleagues and then heard that NYC Mayor Bloomberg was going to use it to learn to code (why, I have no earthly idea).

AND, it was the magic price of FREE.

Given that I’m learning this on my own and don’t have the bandwidth (being a mom, and a consultant, and a director of a non-profit) to actually go to a class at night…and my current employer doesn’t have a training budget…

I finished the first group of lessons yesterday and I can say that, while I didn’t go completely batty, it was a challenge:

Notice, my super awesome 100% complete on the first series of lessons!

Anyway, the biggest issue I have with JavaScript is that it is very case-sensitive. I spent 10 minutes trying to figure why the simplest line of code wouldn’t work – it turns out that I had capitalized the F in function when that’s, obvious to me now, a no-no. Here’s the culprit:

Figuring out that that can’t be capitalized = 10 minutes of my life that I won’t get back.

Codecademy does the whole points, achievements, badges thing that’s all the rage among sites now. I have no idea what the points are for, and while I like the little badges, I won’t be posting them to Facebook, which they encourage you to do.

So, I’m chugging along, trying to remember what it was like learning HTML and CSS way back when. I keeping picturing myself as a JavaScript Ninja…someday.

Are you taking on new languages while building help? If so, which ones?

If you’re a tech writer or an online help developer, you know that documentation, help, and training always always always are left to the end of development and then done in a rush. In almost 20 years of work experience, my current employer is the only one I’ve worked for who actually builds help in to the regular development schedule.

Now, having said that, I don’t mean that there is room left in the schedule for help development and testing…I mean that I am expected to write help as the software is being coded.

The challenge to this help development model is: how do you write help for features that don’t exist yet?!

I’ve come across a number of options and I’d like to hear from you when and from what sources do you write your help.

Help From Working Software

This is the dream scenario where I have software on which I can push buttons and actually write help based on what is happening on the screen. I have had this experience a number of times and I can’t find the words to describe how wonderful it is.

Of course, there’s the issue that buttons may change or some of the UI may change…but there’s nothing like writing help for a working app.

Writing help from software that works is efficient, requiring the fewest number of edits, and rewarding.

Layouts

This is what we call them here….a full-color, annotated set of layouts built by our graphic designer. These layouts take the requirements, use cases, and wireframes and turn them in to tools from which the programmers, and in many cases, the help developer build their code. An example of a layout is shown here:

I’ve left out the notes on the right side of the page – but you can see where the designer has annotations for the programmers. These annotations discuss button behavior, contents of pull-down lists, styling of numbers in fields, etc. Note, also, the placement of Context Sensitive Help tags (the question marks) early in the design process.

Are they as easy to use as working software? No. But they provide a framework from which a help developer can begin writing.

The assumption that comes from working with layouts is that the resulting software or application may not match the layout exactly. This could be caused by a programmer not referring to the layouts (which never happens, does it?!), time running out on the release and finessing doesn’t happen, or finding out that a part of the layout is simply not feasible. And when any of these happen, either the help has to change OR the software code has to change OR the layouts and help are edited to fit the new reality.

When you write from layouts, you must set the expectation that you’ll be rewriting something some where along the line. And don’t even consider using screenshots! That would be an exercise in futility and frustration. Screenshots should wait until after testing, if possible, to reduce the chances of having to replace them because the UI changes.

Wireframes

This is, really, the worst case scenario. Writing help from wireframes is not recommended and not an efficient use of a help developer’s time because the design and UI hasn’t really been hammered out yet. However, you may be called upon to write help from wireframes. And if so, I’m sorry. It’s no fun.

There will be tons of edits, lots of rewriting, new topics created, old topics thrown out – just overall chaos and mayhem.

The only advantage I can see from working from wireframes is that it gives you something to work with. I’ve had to write help from wireframes and I used them almost exclusively to build a rough skeleton of the help. I can create topics from them, build a TOC, roughly identify locations for CSH tags, and just work towards some semblance of help.

Have you ever written help from wireframes? Layouts? What kind of time are you given to write help for software? I’d love to hear from you.