Focusing on customers, rather than on fellow writers, I have switch to writing in Hebrew, on an Israeli-based platform. From time to time, I find it irresistable to communicate with other writers, so I extensively comment to their posts on their blogs.
My main focus, though, is my next customer. Keeping that in mind, and writing a book aimed at the Israeli hi-tech venturer who would like to recruit a writer, I blog only in Hebrew.
You see, one of the beautiful aspects of being a writer in Israel, is that the customer prefers not to read English at all. This facts defines the Israeli market (along with other factors, though). Writing to my potential customer in English, is like... not writing at all.
Thanks for everyone who've read me so far.
Monday, October 15, 2007
Monday, July 9, 2007
Katriel of Method M says that DITA is the least worse approach to documentation. I sadly agree. I don't know DITA, so what I am actually agreeing to, is the concept of "least worse". Whenever I find myself telling my managers about the poverty of the tools I use, I end up frustrated. They are willing to open up their check-books, it is me who tells them to save their money, as to be able to write, circulate for feedback and deliver 2000 topics/year, MS-Word is the only tool available.
MS-Word???
Yes, I answer, exactly because it is the least worse tool. Although I write with RoboHelp as a primary source, and CHM a primary output, I admit it is no better than Word.
But there is a solution, say the DITA people.
DITA, they say, will save me from myself. I admit that I don't exactly know what DITA does. It is said to ease the ability to deliver multiple types of outputs. However, I ask, why deliver multiple types of output in the first place? No one read printed documentation anymore, and for on-line readers, no one can tell the difference between PDF and CHM. They're both easy to navigate, search, and find what you are looking for.
Let's take a different angle. Suppose I throw everything I write to a single website. Suppose that this website is well protected (acceessible only to registered users, for example) and well accessible (it takes a fraction of a second to perform a search, and the search returns excellent results). Now, looking, for example, for installation guidelines for some product of mine, wouldn't it be safe to assume that the readers won't mind whether the piece of information they're after is titled "installation guide" or "installation notes for version 1.1.0.35" or "fix to defect #35022"?
If my assumption is correct, piling everything I write onto a single website will eliminate the entire single-sourcing empire (an empire of pit-falls, if I may). No more DOC-to-CHM, RoboHelp-to-PDF. Wow. This is a Wow, no less.
So, this leave me with what Katriel calls "DITA is a standard — and is implemented using topic-centered and minimalism (methodology)". I'd buy this guidlines anytime.
MS-Word???
Yes, I answer, exactly because it is the least worse tool. Although I write with RoboHelp as a primary source, and CHM a primary output, I admit it is no better than Word.
But there is a solution, say the DITA people.
DITA, they say, will save me from myself. I admit that I don't exactly know what DITA does. It is said to ease the ability to deliver multiple types of outputs. However, I ask, why deliver multiple types of output in the first place? No one read printed documentation anymore, and for on-line readers, no one can tell the difference between PDF and CHM. They're both easy to navigate, search, and find what you are looking for.
Let's take a different angle. Suppose I throw everything I write to a single website. Suppose that this website is well protected (acceessible only to registered users, for example) and well accessible (it takes a fraction of a second to perform a search, and the search returns excellent results). Now, looking, for example, for installation guidelines for some product of mine, wouldn't it be safe to assume that the readers won't mind whether the piece of information they're after is titled "installation guide" or "installation notes for version 1.1.0.35" or "fix to defect #35022"?
If my assumption is correct, piling everything I write onto a single website will eliminate the entire single-sourcing empire (an empire of pit-falls, if I may). No more DOC-to-CHM, RoboHelp-to-PDF. Wow. This is a Wow, no less.
So, this leave me with what Katriel calls "DITA is a standard — and is implemented using topic-centered and minimalism (methodology)". I'd buy this guidlines anytime.
Monday, June 25, 2007
Blogging as a form of Procrastination
Inpired by this post I am pleased to announce that earlier this month I have shut down two blogs of mine. Yeap, you don't have to be a teen to have multiple blogs aimed at multiple audience.
The two deceased blogs were quite busy. I wrote 3-5 posts a week per each. I t was fun, it was productive, it help me to a achieve a well set goal and learn something about myself, all in a package of a blog that I could shut down just like that.
Mabe that is exactly the point. Sure, blogs are procrastination. But, they are so as a form of documenting scattered thought. (I alomost worte "managing thoughts") Real life - if held correctly - are purposeful. Blogging - if taken to what they are - are everything else. Blogging means thinking freely. Thinking freely means thinking randomly. Randomness won't achieve any goal for me, but it allows me to recreate and to keep track of my thought at the same time.
The next thought that has just popped up is that procrastination is demoting a short-term goal my daily tasks) for a longer one. Longer, and less definite. Now, I don't know wxactly what I meant by this one, but hey, this is what blogging is all about - keeping track of this halfbaked thought in order to be able to return to it later on.
The two deceased blogs were quite busy. I wrote 3-5 posts a week per each. I t was fun, it was productive, it help me to a achieve a well set goal and learn something about myself, all in a package of a blog that I could shut down just like that.
Mabe that is exactly the point. Sure, blogs are procrastination. But, they are so as a form of documenting scattered thought. (I alomost worte "managing thoughts") Real life - if held correctly - are purposeful. Blogging - if taken to what they are - are everything else. Blogging means thinking freely. Thinking freely means thinking randomly. Randomness won't achieve any goal for me, but it allows me to recreate and to keep track of my thought at the same time.
The next thought that has just popped up is that procrastination is demoting a short-term goal my daily tasks) for a longer one. Longer, and less definite. Now, I don't know wxactly what I meant by this one, but hey, this is what blogging is all about - keeping track of this halfbaked thought in order to be able to return to it later on.
Thursday, May 17, 2007
A semi-wiki documentation trial
I consider myself as "highly pro-wiki, yet the worst salesperson I could think of". I believe wiki is fantastic, yet I fails to pass the argument that an SME * who already reviews a document would benefit from a Wiki platform more that form the MS-Word track changes features that is currently in use.
For several years, I look at such posts with a great envy. Trust, tolerance and confidence are important, of course, but something else is missing. I can't get people to write into a wiki and I can't think of the reason why.
Last week I was asked to write a 2-3 paper one some new feature. It's a command-line operated tool, not very intuitive for me, so I asked R&D for some extra help here. I stored the document on a public domain and send them the link with a general comment that says "please read and comment, thanks".
They were great. Within a day, three developers has commented, raising new questions, answering some other questions, extending the document a little because the feature has evolved, etc.
Of course, I had to go over the text, move some from the comment boxes into the document itself, accept and reject changes, etc. But, the document was extensively written by developers who were happy - and agile - to contribute.
Now, our major documentation set is hundreds of pages long (to each direction :-), so I believe we;ll take it one step at a time.
* This is the guy over the cubicle who is not a tech writer.
For several years, I look at such posts with a great envy. Trust, tolerance and confidence are important, of course, but something else is missing. I can't get people to write into a wiki and I can't think of the reason why.
Last week I was asked to write a 2-3 paper one some new feature. It's a command-line operated tool, not very intuitive for me, so I asked R&D for some extra help here. I stored the document on a public domain and send them the link with a general comment that says "please read and comment, thanks".
They were great. Within a day, three developers has commented, raising new questions, answering some other questions, extending the document a little because the feature has evolved, etc.
Of course, I had to go over the text, move some from the comment boxes into the document itself, accept and reject changes, etc. But, the document was extensively written by developers who were happy - and agile - to contribute.
Now, our major documentation set is hundreds of pages long (to each direction :-), so I believe we;ll take it one step at a time.
* This is the guy over the cubicle who is not a tech writer.
tech_writer_blog_directory
I have added myself to this directory.
Thank you, Anne Gentle of BMC, for telling about it.
Anne's latest posts deal with using Wiki for documentation, a topic I will extensively write about.
Thank you, Anne Gentle of BMC, for telling about it.
Anne's latest posts deal with using Wiki for documentation, a topic I will extensively write about.
Thursday, April 26, 2007
Creating an Image Report with RoboHelp
When I discovered that my primary layot is On-Line Help, and therefore switched from writing with MS-Word to writing with RoboHelp, I have started to hide my screenshots.Instead of presenting the reader a set of steps that span through several pages, I deliver a 10-rows-long text-only set of steps whose screenshots are hidden behind the text. Clicking a step reveals the screenshots and most of the readers are usually happy with that.
The problem within this arrangement is the way I maintain these screenshots. Ever so often I am required to update the On-Line Help to match the product's new GUI. In some of these cases, only the GUI changes, while the logic (the way the user uses the application) remains intact. Such a screenshot replacement should be a breeze. It is, indeed, very easy, given that I know where my screenshots are.
How do I know that?
Writing into MS-Word, I simply run through the pages, look at the shots and replace them on the spot. RoboHelp is less intuitive here (no such thing as run through the pages...) but it provides an Image Report.
Quickly bypassing the report's pitfalls (Selecting All Folders doesn’t recognize Conditional Build Tags; Selecting a parent folder results in an empty report) we come up with a list of all images per topic. Properly laying out the topics (i.e. one task sequence per topic), the images read task1-image1.gif, task1-image2.gif, etc.
(Blogger allows for a single picture per post, so no more images for you. Come back other day.)Writing into MS-Word, I simply run through the pages, look at the shots and replace them on the spot. RoboHelp is less intuitive here (no such thing as run through the pages...) but it provides an Image Report.
Quickly bypassing the report's pitfalls (Selecting All Folders doesn’t recognize Conditional Build Tags; Selecting a parent folder results in an empty report) we come up with a list of all images per topic. Properly laying out the topics (i.e. one task sequence per topic), the images read task1-image1.gif, task1-image2.gif, etc.
Earlier this week I have copied such a report into an MS-Word file, along with tiny-little-hand-crafted screenshots icons. Too much work.
Generating the report on a daily basis throughout the project, should do.
Wednesday, April 18, 2007
Flatland - the metaphor works in both directions
BlogScholar (to whom I have arrived via Commitment to Living) writes that academics should leverage themselves through the blogosphere.
I am not going to add my two cents to the "of course you should have a blog or two, too". Instead, I would like to state that one of reasons I'll probably won't see the university from within is that all I need to know is available on-line.
Sure, there are lots of things I would like to learn. Moreover, there are plenty of things I need to learn (for example, in order to stay in the business).
However, instead of driving to the nearby university campus, guessing whether I have chosen the right professor for my needs, guessing I know what my academic needs are, and keeping them from evolving throughout a 13-weeks long semester, *
instead of doing all that, I am quick-searching a subject, read a post or two (or two-dozens, depends on how long does it take me to get it straight), post several comments with questions, and always get a decent feedback from the blogger.
The land is, indeed, not flat anymore, and it works for non-academics as well.
* OK, no English professor would ever allow me to write such a long sentence. Maybe the university has a point after all ;-)
I am not going to add my two cents to the "of course you should have a blog or two, too". Instead, I would like to state that one of reasons I'll probably won't see the university from within is that all I need to know is available on-line.
Sure, there are lots of things I would like to learn. Moreover, there are plenty of things I need to learn (for example, in order to stay in the business).
However, instead of driving to the nearby university campus, guessing whether I have chosen the right professor for my needs, guessing I know what my academic needs are, and keeping them from evolving throughout a 13-weeks long semester, *
instead of doing all that, I am quick-searching a subject, read a post or two (or two-dozens, depends on how long does it take me to get it straight), post several comments with questions, and always get a decent feedback from the blogger.
The land is, indeed, not flat anymore, and it works for non-academics as well.
* OK, no English professor would ever allow me to write such a long sentence. Maybe the university has a point after all ;-)
Subscribe to:
Posts (Atom)
