Many of us write various kinds of documentation in English. That includes presentations, user guides, help files, and just plain blog posts. I’m the same way. We teach people with screencasts, where you have to explain what’s happening on the screen. The scripts contain a lot of descriptions of different controls, like “open the File menu,” “click the OK button,” “select the Options tab.” I couldn’t figure out how to write this correctly in English. Should I use articles? In what order should I write the control and its name?
Question for the readers: which is correct:
-
Select menu **Open **
-
Select Open menu
-
Select the Open menu
Or in this case:
-
Press button OK
-
Press OK button
-
Press the OK button
I spent six months racking my brain, I couldn’t sleep, I forgot about every other pastime except reading the dictionary and grammar references. When I was taking the train on a business trip, I looked out the window, and instead of trees, buttons, little menus, and radio buttons ran past my eyes. While pondering this question, several times at the terminal station of the subway I forgot to get out of the car and rode off to the depot. When I was getting money at the bank, the teller asked me, “Full name?” and I answered, “drop-down list.” At the registry office, to the question “Do you?” I answered, “No to all.” I would walk up to random passersby on the street with these questions, but they would only make the crazy sign and walk away...
The eclipse is over. My mind is so clear, and now I see what awaits us.
At this link http://msdn.microsoft.com/en-us/library/aa511258.aspx, Microsoft employees describe guidelines for designing application interfaces for Microsoft Windows, including documentation guidelines for every possible type of control.
Thus, none of the options above are correct. The correct options are: “Click File,” “Click OK.”
If you want to be literate, this documentation is required reading. There are many controls, and the recommendations are different for all of them.
Did you know about these rules? Or have you been so smart since school that you write in English without mistakes? Do you even care whether you write correctly in English or Russian? All bloggers who give a damn are invited to the comments.
P. S. And after our last conversation about design in documentation, did anyone find any decent templates for Doxygen?