Karen left for work and, shortly after she left, she called to say that if I was going to go into work, I should leave sooner than later. I was out the door and at work shortly before 7, not going above about 40 MPH on I-80.
Work was like a graveyard. I went to my 8 AM meeting and at 7:55, I was the only one there. The Project Manager arrived right around 8 and then about 6 others on the project team arrived at about 8:10 AM. The meeting was interesting and I'm glad I went. I was tempted to sit at my desk and dial in to the meeting using WebEx. Kind of at the last minute, I decided to go down to the actual meeting room.
The reason the meeting was interesting is that there was a demo of some new functionality. The new functionality performs the same type of task that is performed in a different part of the system. The way the user accomplishes the task is different. The UI is different, the way the screen is laid out is different, the buttons used to do the actual task are different, and it just has a very different look and feel. The question that was asked was, "Why are we requiring the user to learn two different ways to accomplish the same task?"
Crickets.
During the meeting, when the developer started asking questions, I didn't add to the discussion. I could have spoken and added my perspective at the meeting but, for whatever reason, I did not.
During the 5 minute walk back from the meeting room to my desk, I talked with both a Quality Assurance software tester and a developer (not the one who had raised the question) on the team. The discussion centered around how the system shouldn't look like one team did one area and another team did another area. There should be a single look and feel. I said that from a technical writer perspective, as someone who has the assigned task to document how to accomplish tasks, it would be much easier if there was a single way instead of having one area work differently than another. The QA tester agreed. He would have the same issue - in one area, the functionality works one way and in another area, the functionality works a different way.
After the meeting I saw the developer who had raised this discussion. I apologized, whether I needed to or not, and said that I should have jumped in and added to the discussion. We talked about how there should be a central way to do the same task in different parts of the system and that it shouldn't look like a different implementation of the same functionality somewhere else. We talked about sharing code within the system. I talked about the vision I have a single source solution for our documentation where instead of writing a procedure once and pasting it into multiple documents, we'd have the procedure written once and that 'chunk' of text would be used for all clients that can do that same procedure in the system.
It's an ideal I will probably spend a lot of time writing about on this blog between now and the end of the year. It's really important to me. I do not want to be writing at the end of January 2014 the following:
"Well, a year ago, I wrote about having a single source and writing a procedure once and using it for all clients. What should have been accomplished between now and today has not been accomplished."
If I have to write that on January 30, 2014, I will be unhappy, to understate what I would feel.
There. I feel better.
The rest of my day, from about 10 AM until 5, was also kick butt. I worked on documentation changes for our next release. I updated a user guide to use the new standard template I want to use for all documents. There are character styles for every time you would want to select text and then press Ctl+B to make that text bold or to change the indentation of the text or any attribute that defines what the text looks like. All of that, like CSS does for HTML, controls the formatting and separates content from presentation. This is not a new idea - there are numerous websites that talk about this, that describe the principles behind it, that describe the benefits - so I won't regurgitate it here.
A brief example is I have a character style for buttons. I define a character style and call it "Button" within the template. I define this "Button" style as follows:
|
Verdana
11 pt
Bold.
|
I apply that character style to all places I have a button in the text. Then, if I want to change the way buttons look - say I want all buttons to have a gray background - then I simply change the definition and all those instances of the "Button" style are magically updated. It's not magic - it's the way MS Word works. We use Word at work so when I talk about this type of stuff, I'm talking specifically about MS Word. I know that InDesign has the same type of idea where you can define character styles as well.
I like writing about all this. It's going on 6 years that I've been thinking about all of this. It was in 2007, at the WinWriters conference in Long Beach, CA, that this idea really took off in my head. I think it might have been Dave Gash that was talking about this in one of his sessions and it just clicked. I remember going back to the CSS file I was using at the time and realized that anytime I had wanted to make text bold, I used a single span class and called it "programname." That span class was applied to all text I wanted to be bold - whether it was a button, a check box label, a drop-down list label, or a menu option. I set out to convert all of the HTML files in that help system to not use that single span class "programname" for making text bold.
The idea looks like this, when implemented:
See how there's a "fieldname" span class and a "fieldvalue" span class? That's what I'm talking about. Instead of manually making the text bold and not being able to make global changes, there's a separation of content and presentation.
That's what I want. That's what I feel driven to do in the next year at work.
And that's what I am going to work extra hours to achieve.
No comments:
Post a Comment