A rarely seen combination of colors, which I find refreshing and relaxing at the same time; it combines very well with a gray grid.
Saturday, 31 January 2009
Bullets
A rarely seen combination of colors, which I find refreshing and relaxing at the same time; it combines very well with a gray grid.
Friday, 30 January 2009
NM-art
This picture is dedicated to Antonio Triolo (who conied the term NM-art) and Antonio Guidi (who believes this art should be exploited to make money).
What you see is a fragment of a TOCSY, very out-of-phase.
Tuesday, 20 January 2009
Writing an Help Book
I don't consider myself an expert in software documentation. I have written hundreds of manual pages for the programs that I have written in the last 20 years, but I did it reluctantly, just because nobody else was going to do it.
Having dedicated the last two months of my life to write another manual (which is not finished yet), I like to share with you my thoughts and my personal rules.
The source of inspiration, this time, has been the Apple Help Programming Guide. Sounds obvious? They certainly have more experience than myself, so why not exploiting it? First doubt: many third party applications deliver their documentation in other forms, for example as PDF files. Second exception: Apple itself, when a program is more professional, like in the case of XCode, avoids its own Help Viewer. Third doubt: it's normally good to follow Apple guidelines, because users already know how the interface works, but is this theory still valid in this particular case? Do they read the manuals of, let's say, Mail or Safari?
While the Help Viewer has its drawbacks, the advantages are too many: it's searchable from the menu-bar and this fact alone makes it the best choice. It makes no difference if you are writing the manual for a simple unprofessional application or for a complex one (a scientific one, in our case). It's true that we should expect a little more sacrifice from researchers (they can't say they don't like studying!), yet their situation really requires simplified manuals. Speaking for myself, there are applications that I rarely use, until I need them to solve some specific tasks. It would be great to find the answers I need, explained in plain terms, easy to understand even without reading the rest of the manual.
That's exactly the main principle of the the Apple Help. Apple says: don't write a feature-oriented manual. That would be, for example, an orderly description of what each menu command does. What they say, instead, is: identify the typical tasks (workflows) the user is faced to and write a page for each of these workflows. The approach is more popular than it might appear. Consider, for example, the case of a department buying a site license for a new program, that nobody knows and that is accompanied by a 1,000 pages manual. The boss can't tolerate that all his employees study 1,000 pages of manual. He will ask one of them to study it and write down a condensed (2-pages!) "how-to", with sequential, step-by-step instructions for the most common tasks. Now, if the manual already comes with many of these "how-to" to choose from, all the boss has to do is to photocopy one of them. Isn't it a time-saving?
Also consider the usual job of an help desk. They are asked by the user: "I want to do this but the program doesn't allow me to". Here again, the answer usually comes either as a list of steps to repeat or a list of conditions to verify.
The third reason why a task-oriented manual saves time is that it's more readable. Why? Because it's outlined, schematic, consistent. The reader can swiftly identify which paragraphs to skip (because he's already familiar with a particular command, for example, or because they treat special cases) and which paragraphs to pay attention to.
I am speaking about saving time, but actually I have lost a lot of my time to write my last "opus", mainly because of a non appropriated strategy and probably also because of non appropriated tools. What I have been doing lately has been to rewrite a manual that I had initially written in 2005, and incrementally updated to reflect the evolution of the program described. The original sin was my decision to put everything into the manual, like short lessons of NMR processing, the promotion of the product itself (who doesn't it?) and personal comments. All these things were motivated but, in the end, it had become difficult to search the manual, because there was too much information and it was not uniform. Hence my new rule: "The manual must be nothing but a comprehensive collection of answers". Tutorials, articles, hands-on lessons, podcasts, etc... are all precious items, but their place, today, is on the web site. When I want to express my opinions and compare alternative programs I have my blog. The manual needn't to be more than a reminder. At the same time, however, any single page should be easy to understand even for a beginner. That's why I don't mind repeating the same advices in many places.
As Apple itself suggests, however, there must also be a few propaedeutic pages. If you browse the guide of the operative system ("Mac help") you can actually recognize four kinds of pages. To take the examples from my own work, they are:.
Before writing a page you have to choose the right format, and the corresponding style. An overview page is explicative; it defines the concepts of the program. A reference page is descriptive. A task page gives straight instructions. A navigation page normally contains links only, into a suggested order for learning. All the navigation pages must be reachable from the entry point (home) of the help book and, taken together, they must provide links to all the other pages.
It's important not to mix two styles into the same page. For the same subject, for example, I have written a reference page, an overview page, and a task page. They used to be a single page in the old edition of the manual. There is, however, a partial and important exception, that I will explain later.
Here is, in practice, how I have proceeded. I have identified those areas of the program that fit well into reference tables, for example the preferences dialog and the keyboard shortcuts, and have written those pages first. They are feature-oriented, therefore relatively easy to write (it's enough to describe the individual options in the order that they appear inside the dialog). To describe the other modules, the first choice is always a task-oriented page. It can be a list of the many available ways to accomplish a given task, or the sequential list of steps (sometimes with ramifications). In practice, I have invented many variations. It's a fact that task pages are more schematic and therefore easier to consult. Deciding which pages to write and their titles is a little more complicated, because there's no ready scheme to follow. In theory you should observe the users at work (with other programs too), hear their FAQ, etc... The titles of the chapters should correspond to the expectations of the users, not to the menus of the program.
In practice, it's still possible to start from the features! For example, I try to remember why I added a certain command, what problem I had in mind, etc.. and I find the typical workflow that incorporates that command. If I identify two or more typical workflows, I write a page for each of them. Their description goes into the central box of the page. Yes, it's not necessary to start from the beginning. It's more convenient to write down only the skeleton of the workflow, then to explain the concepts or what's happening inside the program or the available alternatives, adding these things between the lines. The first sentence of each paragraph contains an instruction to follow, the rest of the paragraph contains the explanations (for the interested reader only). When an important note can't find a place inside the workflow box, it will go either into the introduction or into the conclusion. Here I disagree with Apple's guidelines, because they neglect the most important concept. I think that the manual should give the answers, it shouldn't force the reader to stop and think. A mistake that I try to avoid is to start a chapter with a formal definition that refers to concepts that will be explained in the body below. What's good for a textbook can be bad for an help book. When the reader arrives to a chapter he still doesn't know if he has found what he needs, therefore it's not ready to concentrate on the topic. He needs to be reassured first. The introduction should just refresh a few basic concepts that set the context for what follows. The difficult notions will find their space below the central box. Here is the exception that I was referring earlier. While the overview and the reference pages are more unitary, a task page, being graphically divided into three regions (introduction, workflow-box and conclusion), can contain all things. The introduction can become, if necessary, an overview section and the conclusion a reference section (it can describe rare cases and special usages). Obviously, if I see that any of these sections becomes too long I will move it into its own page. More often than not, however, it's possible to cover a whole subject with one or two task-pages, using the described technique of writing between the lines. In practice my manual contains 13 overviews, 15 reference tables and 44 task pages. The last group is destined to grow: as new questions arrive from the users, I am going to add new workflows.
While Apple encourages to add pictures, actions (scripts) and multimedia content into an help book, I see a clear trend, by their side, toward text-only manuals (and I have followed suit). While it's true that the right picture can be an ace, and sometimes it is really necessary, I agree that they should be added only in such a case. To say which command to use, for example, I prefer mentioning the menu and the name of the command, rather than showing the icon to click. The icons are just shortcuts and the user should discover these shortcuts by herself. Adding a picture has a drawback: the page exceeds the limits of the screen and it's no more possible to see the whole workflow with a glance. Apple really succeeds into containing each page into a small size. I am not as good. Anyway, when each element of the program interface clearly shows its name, there's no difficulty in describing it without the aid of pictures.
Don't you think it's better to follow the inverse approach, namely to add a short explicatory message into a window instead than to reproduce the window itself into the manual? Actually, having deliberated to write a task-oriented manual, which doesn't list each and every command, it's useful to design a self-explicatory interface. Indeed I have renounced to write pages to describe some commands that were sufficiently covered by their yellow help tips.
Another thing that Apple uses sparingly are the internal links, which instead I use extensively (they are the main reason, after all, why I prefer HTML manuals).
Things that they use a lot but I would discourage are several Apple extensions to the HTML tags (for example, all the lists of links in their help books are created dynamically). The Help Viewer, for those who ignore it, recognizes a few special instructions which are not as good as they seem at first sight. I have so many reasons to prefer standard XHTML: the manual looks the same into a normal browser, so there's no need to test it with the Help Viewer (not an easy thing) and the user is free to read the manual with the browser of her choice. The whole manual can be uploaded on the web (it becomes easier to give a link to a specific page, as I have done inside this article). Last but not least, the Help Viewer, which is normally so sluggish, becomes much faster when the HTML files do not contain the special tags! Anyway, the meta "description" tag is a necessity, like the tag: meta name="robots" content="noindex" in the index pages (you don't want an index page to appear as a result of a search).
You may be curious to know which tools I have used. Actually I have simply duplicated a few files from the Apple's help books installed on my iMac and substituted their text with mine. By inspecting the XHTML code I got the impression it was generated by a computer, but I haven't investigated further. I have used Smultron, by Peter Borg, because it's what I am currently using to edit my HTML and CSS files, and I admit that it's less than ideal, yet I haven't felt the need for anything more refined. For the sake of your curiousity, the manual of Smultron is a PDF file!
If you have to document your own program, and can describe it in a few pages, than you don't have to ponder your strategy too much. You can just unleash your ingenuity and the manual will likely be a masterpiece. If, instead, the program to describe is complex, and you still want to follow Apple's guidelines, be prepared to spend a considerable amount of time. I don't know if my rules can work for you, maybe you'll find better strategies or stick strictly to the official guidelines. I have just enjoyed to share my experience, for what it's worth.
Don't be disappointed if my story ends with a sad note. Whenever my manual will be finished, I am not expecting any particular feedback from its readers. Half of the users of the program don't read the manuals and the rest have no time to write a line. I'll remain my only judge. That's probably why so many guys like programming and so few like writing technical documentation. I have tried both and let me say that they are arts of the same level of difficulty.
Having dedicated the last two months of my life to write another manual (which is not finished yet), I like to share with you my thoughts and my personal rules.
The source of inspiration, this time, has been the Apple Help Programming Guide. Sounds obvious? They certainly have more experience than myself, so why not exploiting it? First doubt: many third party applications deliver their documentation in other forms, for example as PDF files. Second exception: Apple itself, when a program is more professional, like in the case of XCode, avoids its own Help Viewer. Third doubt: it's normally good to follow Apple guidelines, because users already know how the interface works, but is this theory still valid in this particular case? Do they read the manuals of, let's say, Mail or Safari?
While the Help Viewer has its drawbacks, the advantages are too many: it's searchable from the menu-bar and this fact alone makes it the best choice. It makes no difference if you are writing the manual for a simple unprofessional application or for a complex one (a scientific one, in our case). It's true that we should expect a little more sacrifice from researchers (they can't say they don't like studying!), yet their situation really requires simplified manuals. Speaking for myself, there are applications that I rarely use, until I need them to solve some specific tasks. It would be great to find the answers I need, explained in plain terms, easy to understand even without reading the rest of the manual.
That's exactly the main principle of the the Apple Help. Apple says: don't write a feature-oriented manual. That would be, for example, an orderly description of what each menu command does. What they say, instead, is: identify the typical tasks (workflows) the user is faced to and write a page for each of these workflows. The approach is more popular than it might appear. Consider, for example, the case of a department buying a site license for a new program, that nobody knows and that is accompanied by a 1,000 pages manual. The boss can't tolerate that all his employees study 1,000 pages of manual. He will ask one of them to study it and write down a condensed (2-pages!) "how-to", with sequential, step-by-step instructions for the most common tasks. Now, if the manual already comes with many of these "how-to" to choose from, all the boss has to do is to photocopy one of them. Isn't it a time-saving?
Also consider the usual job of an help desk. They are asked by the user: "I want to do this but the program doesn't allow me to". Here again, the answer usually comes either as a list of steps to repeat or a list of conditions to verify.
The third reason why a task-oriented manual saves time is that it's more readable. Why? Because it's outlined, schematic, consistent. The reader can swiftly identify which paragraphs to skip (because he's already familiar with a particular command, for example, or because they treat special cases) and which paragraphs to pay attention to.
I am speaking about saving time, but actually I have lost a lot of my time to write my last "opus", mainly because of a non appropriated strategy and probably also because of non appropriated tools. What I have been doing lately has been to rewrite a manual that I had initially written in 2005, and incrementally updated to reflect the evolution of the program described. The original sin was my decision to put everything into the manual, like short lessons of NMR processing, the promotion of the product itself (who doesn't it?) and personal comments. All these things were motivated but, in the end, it had become difficult to search the manual, because there was too much information and it was not uniform. Hence my new rule: "The manual must be nothing but a comprehensive collection of answers". Tutorials, articles, hands-on lessons, podcasts, etc... are all precious items, but their place, today, is on the web site. When I want to express my opinions and compare alternative programs I have my blog. The manual needn't to be more than a reminder. At the same time, however, any single page should be easy to understand even for a beginner. That's why I don't mind repeating the same advices in many places.
As Apple itself suggests, however, there must also be a few propaedeutic pages. If you browse the guide of the operative system ("Mac help") you can actually recognize four kinds of pages. To take the examples from my own work, they are:.
Before writing a page you have to choose the right format, and the corresponding style. An overview page is explicative; it defines the concepts of the program. A reference page is descriptive. A task page gives straight instructions. A navigation page normally contains links only, into a suggested order for learning. All the navigation pages must be reachable from the entry point (home) of the help book and, taken together, they must provide links to all the other pages.
It's important not to mix two styles into the same page. For the same subject, for example, I have written a reference page, an overview page, and a task page. They used to be a single page in the old edition of the manual. There is, however, a partial and important exception, that I will explain later.
Here is, in practice, how I have proceeded. I have identified those areas of the program that fit well into reference tables, for example the preferences dialog and the keyboard shortcuts, and have written those pages first. They are feature-oriented, therefore relatively easy to write (it's enough to describe the individual options in the order that they appear inside the dialog). To describe the other modules, the first choice is always a task-oriented page. It can be a list of the many available ways to accomplish a given task, or the sequential list of steps (sometimes with ramifications). In practice, I have invented many variations. It's a fact that task pages are more schematic and therefore easier to consult. Deciding which pages to write and their titles is a little more complicated, because there's no ready scheme to follow. In theory you should observe the users at work (with other programs too), hear their FAQ, etc... The titles of the chapters should correspond to the expectations of the users, not to the menus of the program.
In practice, it's still possible to start from the features! For example, I try to remember why I added a certain command, what problem I had in mind, etc.. and I find the typical workflow that incorporates that command. If I identify two or more typical workflows, I write a page for each of them. Their description goes into the central box of the page. Yes, it's not necessary to start from the beginning. It's more convenient to write down only the skeleton of the workflow, then to explain the concepts or what's happening inside the program or the available alternatives, adding these things between the lines. The first sentence of each paragraph contains an instruction to follow, the rest of the paragraph contains the explanations (for the interested reader only). When an important note can't find a place inside the workflow box, it will go either into the introduction or into the conclusion. Here I disagree with Apple's guidelines, because they neglect the most important concept. I think that the manual should give the answers, it shouldn't force the reader to stop and think. A mistake that I try to avoid is to start a chapter with a formal definition that refers to concepts that will be explained in the body below. What's good for a textbook can be bad for an help book. When the reader arrives to a chapter he still doesn't know if he has found what he needs, therefore it's not ready to concentrate on the topic. He needs to be reassured first. The introduction should just refresh a few basic concepts that set the context for what follows. The difficult notions will find their space below the central box. Here is the exception that I was referring earlier. While the overview and the reference pages are more unitary, a task page, being graphically divided into three regions (introduction, workflow-box and conclusion), can contain all things. The introduction can become, if necessary, an overview section and the conclusion a reference section (it can describe rare cases and special usages). Obviously, if I see that any of these sections becomes too long I will move it into its own page. More often than not, however, it's possible to cover a whole subject with one or two task-pages, using the described technique of writing between the lines. In practice my manual contains 13 overviews, 15 reference tables and 44 task pages. The last group is destined to grow: as new questions arrive from the users, I am going to add new workflows.
While Apple encourages to add pictures, actions (scripts) and multimedia content into an help book, I see a clear trend, by their side, toward text-only manuals (and I have followed suit). While it's true that the right picture can be an ace, and sometimes it is really necessary, I agree that they should be added only in such a case. To say which command to use, for example, I prefer mentioning the menu and the name of the command, rather than showing the icon to click. The icons are just shortcuts and the user should discover these shortcuts by herself. Adding a picture has a drawback: the page exceeds the limits of the screen and it's no more possible to see the whole workflow with a glance. Apple really succeeds into containing each page into a small size. I am not as good. Anyway, when each element of the program interface clearly shows its name, there's no difficulty in describing it without the aid of pictures.
Don't you think it's better to follow the inverse approach, namely to add a short explicatory message into a window instead than to reproduce the window itself into the manual? Actually, having deliberated to write a task-oriented manual, which doesn't list each and every command, it's useful to design a self-explicatory interface. Indeed I have renounced to write pages to describe some commands that were sufficiently covered by their yellow help tips.
Another thing that Apple uses sparingly are the internal links, which instead I use extensively (they are the main reason, after all, why I prefer HTML manuals).
Things that they use a lot but I would discourage are several Apple extensions to the HTML tags (for example, all the lists of links in their help books are created dynamically). The Help Viewer, for those who ignore it, recognizes a few special instructions which are not as good as they seem at first sight. I have so many reasons to prefer standard XHTML: the manual looks the same into a normal browser, so there's no need to test it with the Help Viewer (not an easy thing) and the user is free to read the manual with the browser of her choice. The whole manual can be uploaded on the web (it becomes easier to give a link to a specific page, as I have done inside this article). Last but not least, the Help Viewer, which is normally so sluggish, becomes much faster when the HTML files do not contain the special tags! Anyway, the meta "description" tag is a necessity, like the tag: meta name="robots" content="noindex" in the index pages (you don't want an index page to appear as a result of a search).
You may be curious to know which tools I have used. Actually I have simply duplicated a few files from the Apple's help books installed on my iMac and substituted their text with mine. By inspecting the XHTML code I got the impression it was generated by a computer, but I haven't investigated further. I have used Smultron, by Peter Borg, because it's what I am currently using to edit my HTML and CSS files, and I admit that it's less than ideal, yet I haven't felt the need for anything more refined. For the sake of your curiousity, the manual of Smultron is a PDF file!
If you have to document your own program, and can describe it in a few pages, than you don't have to ponder your strategy too much. You can just unleash your ingenuity and the manual will likely be a masterpiece. If, instead, the program to describe is complex, and you still want to follow Apple's guidelines, be prepared to spend a considerable amount of time. I don't know if my rules can work for you, maybe you'll find better strategies or stick strictly to the official guidelines. I have just enjoyed to share my experience, for what it's worth.
Don't be disappointed if my story ends with a sad note. Whenever my manual will be finished, I am not expecting any particular feedback from its readers. Half of the users of the program don't read the manuals and the rest have no time to write a line. I'll remain my only judge. That's probably why so many guys like programming and so few like writing technical documentation. I have tried both and let me say that they are arts of the same level of difficulty.
Subscribe to:
Posts (Atom)