tag:blogger.com,1999:blog-15203466637713099452024-03-05T13:16:42.087+05:30Writing TechnicallyAnindita Basu's blog on technical communication, in which she talks about technical writing, editing, DITA, and user experience.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.comBlogger69125tag:blogger.com,1999:blog-1520346663771309945.post-62715649703664036132016-01-01T23:51:00.000+05:302016-01-02T15:51:04.910+05:30Session takeaways: the STC India annual conference 2015About a month ago, I attended the STC India annual conference at Pune. That it's been a month and it's still playing on my mind is proof that, this time, I had solid takeaways from the conference (this doesn't happen every time, you know). In this blog post, I will talk about those takeaways.<br />
<br />
First, the pre-conference. I think we should do away with the "pre" suffix altogether — it isn't something one *must* do before attending the conference; it's rather something that one does *in* the conference. But, let me not nitpick. Pre-conference, <b>Vidhya VKumar</b> and I took a day-long workshop on writing with DITA. This meant that I missed an excellent track that had workshops on regex (by <b>Savio</b>) and on scripting by techwriters (by <b>Puneet</b>). As soon as I could, I looked at the session slides, and got my first takeaways — pointers to places where I could teach myself regex (as also ReST API, by <b>Punam</b>) and examples of where I can put my scripting (v. v. basic Python) knowledge to good use. I am hoping that the sessions by Savio (regex) and Puneet (scripting) get repeated at an STC city session in 2016, or even better still, at the annual conference of 2016.<br />
<br />
I have always believed I am not cut for management. This perception was reinforced when I looked at the session slides of <b>Bhavana</b> and <b>Brinda</b> (preconference management track). The slides also nudged me to develop myself as a technical expert, and gave sufficient pointers to get me started.<br />
<br />
I must also mention the preconf session slides on strategy by <b>Wasique</b>. To me, the slides look extremely well-thought out and I am sure I would have benefited much had I been physically present at the session. This, again, is one more session that I hope the STC people arrange for a repeat in 2016.<br />
<br />
Day 1 started well, with <b>Wasique</b> (again) on...Bombay films. Well, not really; that part came much much later but I liked the session (seriously) because it explained the WHY of short attention spans. To someone like me who's internalised Twitter, DITA, and progressive disclosure, chunking information comes easily but knowing the science — the real actual neuroscience — behind why doing what I do is good...is great.<br />
<br />
Because there were parallel tracks, I missed a few sessions on Day 1 too (mainly because of a few bad choices). When I looked at the slides of these missed sessions, I regretted not having been at <b>Seema</b>'s session on cognitive load. Again, to me, serving info in byte-sized pieces is natural but we can always (always) learn more, and the slides of this session did have a few takeaways for me.<br />
<br />
Day 2, I missed <b>Mayur</b>'s session on HTML 5. The slides are packed with information; I am sure this was one of the most highly rated sessions at the conference. I did attend the Quick Bytes session: small, 10-minute talks. I loved to tiny little bits <b>Amruta</b>'s talk on logical fallacies in text, and was very impressed with <b>Swati</b>'s journey as an innovator. Then, I went away for <b>Antarchakshu</b>. Folks, if you ever ever ever get a chance to attend one of these sessions (the Xavier's Instt at Bombay does these), do NOT pass the chance up. Before Antarchakshu, "accessibility" was just one more thing to check off a release-readiness list. After Antarchakshu, .... well :) It opened my eyes. It really did.<br />
<br />
And so, yes, these are the sessions that I gained from.<br />
<br />
I look forward to the 2016 conference.<br />
<hr />
Slides and session details of conference are at <a href="http://stc-india.org/conferences/2015/program" target="_blank">http://stc-india.org/conferences/2015/program</a>.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-78656918155939503452015-12-16T19:25:00.001+05:302015-12-19T13:00:28.075+05:30The Udaan publishing storyUdaan is the publication of the STC India annual conference 2015. It was released at the conference that happened between Dec 10 through 12 at Pune. This blog post talks about the backend publishing process.<br />
<br />
Udaan, the name, was conceived by the conference program manager, Mugdha Kulkarni. When she handed the Udaan brief to us, Mugdha was very clear:<br />
<ul>
<li>It should be something that people will keep on their desks for at least a month or two. Not something that goes to the raddiwala on Day 2 of the conference.</li>
<li>If we're having an online version, it should really be a complete digital experience. Not boring web pages.</li>
</ul>
The first item on that list could be addressed by getting good articles. We spread the word around, and when the articles started coming in, and we began to see all the non-boring possibilities in them, it became clear that *just* HTML won't do. We wanted interaction and, consequently, javascript and styling.<br />
<br />
Which became something of a problem, initially. The agency that did the conference web presence put up their hands. What we were asking for needed "programming knowledge", they said, and beyond the scope of free services. Like someone from Allahabad would say, "Itne mein to, bhaiyya, bas itna hi ho payega." <br />
<br />
Which meant, hosting Udaan on stc-india.org, where resided the other pages relating to the conference, would be in direct contravention of the second item in our brief: non-boring web pages. A different hosting site was needed. The next choice seemed easy: a blog. Either Wordpress or Blogger. But wait! We need javascript. Neither free Wordpress nor Blogger are JS-friendly. So, no, we need some other solution. Enter GitHub. <br />
<br />
O dear GitHub, how do I love thee? Let me count the ways:<br />
<ul>
<li>It is free.</li>
<li>It gives you a repository. You store all your content there. And content means *anything*. Any image, any text, any code, any sound, any movie...</li>
<li>It gives you on-click publishing (and a public URL) for your repository content.</li>
<li>It gives you stuff like version control and multi-author checkins and checkouts.</li>
<li>It has its own bugtracker (which we used extensively during the review period).</li>
<li>It takes content out of your laptop (which can crash any day, or whose owner might break an arm) and puts it on its server (which can also crash but at least the hospital scenario is unlikely).</li>
</ul>
Perfect. So, GitHub was to be the platform.<br />
<br />
Now to the content.<br />
<br />
Everything is in HTML. That means, in the beginning, the only tool I needed was Programmer's Notepad 2. Even plain Notepad would've been sufficient, but line numbers and word wrap are handy! The authors sent in their articles in MS Word and I did a paragraph-by-paragraph copy-paste to HTML. Why didn't I just do a Save As in MS Word and generate an HTML file? Because, when an MS Word file is converted to HTML, a lot of unnecessary styling classes get added and, consequently, the end result is not "clean" HTML.<br />
<br />
For the apparent "programming knowledge", I just googled. I had no intention of reinventing the wheel. You'll see that Udaan uses Javascript snippets that are freely available on the net. Udaan also uses styling elements from free CSS available on the net. The main look-and-feel is from the w3schools CSS; I chose it because not only is it the place where many of us learnt our HTML from, but also because their CSS uses responsive design principles. Udaan also uses icons and images available freely on the net. In short, Udaan uses free stuff, thanks to helpful people who think about giving back to the community and therefore share their work so freely.<br />
<br />
But let me talk about content referencing. It's something that's easy in DITA but not so easy in HTML. For consistency, I wanted to use boilerplate text for the headers and footers, and I needed a referencing mechanism that does not need a Ctrl-C + Ctrl-V. The solution that I used is this:<br />
<ol>
<li>Make HTML files with the boilerplate text. For Udaan, the header file contains the Michi masthead, the clickable Udaan heading, and the ToC (accessed through the hamburger menu). The footer file contains the conference date banner, sponsor logos, and code for the scroll-to-top button.</li>
<li>Place the boilerplate files in the same folder that contains the other HTML files that will "call" the boilerplate text. This is important. The referencing mechanism does not work beyond one folder level.<br /><div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3w33ybBfgypImP4Da02NtleIzPmofHOO22HTPa62RGLOggT2kyoJqhJLUYgb4e0C5KD2QA-0oAwP7cQ4eReLDXQ8Bo1zCwT9R40vsGxmHO4Dont5yDl4I8VGl7fqIUwTM4zGDZZSfIr3u/s1600/Snap2.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3w33ybBfgypImP4Da02NtleIzPmofHOO22HTPa62RGLOggT2kyoJqhJLUYgb4e0C5KD2QA-0oAwP7cQ4eReLDXQ8Bo1zCwT9R40vsGxmHO4Dont5yDl4I8VGl7fqIUwTM4zGDZZSfIr3u/s1600/Snap2.png" /></a></div>
</li>
<li>In the file that calls the boilerplate text, insert a <span style="font-family: "courier new" , "courier" , monospace;"><script></span> tag like this:<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjowicMSx3c54L8otKh_XAB42YB_eRxk_y23rqbuf2DT6uu6tB8LfZWymvhTP_vKuL58fjBp4uIJRSVpHfqnXhBt6edU_9_fy8CS6mBtsqNUbh6Pxgz7ge8dNvY8yh91AyZoxuMPEb2g8_p/s1600/Snap3.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjowicMSx3c54L8otKh_XAB42YB_eRxk_y23rqbuf2DT6uu6tB8LfZWymvhTP_vKuL58fjBp4uIJRSVpHfqnXhBt6edU_9_fy8CS6mBtsqNUbh6Pxgz7ge8dNvY8yh91AyZoxuMPEb2g8_p/s1600/Snap3.png" /></a></div>
</li>
<li>At the place where the boilerplate text is needed in the calling file, create a <span style="font-family: "courier new" , "courier" , monospace;"><div></span> tag, like this:<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiNKx_iJwzekGMTRvap84NYGhvpPzZH7mGe4p0ncNLonqxwG8isSDzPr7-KpZPADHlrKgSIvjM6MK3QN-pldcjYKopVflHvsrQFw6eE-GhrhXPnA8VvgnPp68u17AJi1RHQsSn8_GRAQLZD/s1600/Snap4.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiNKx_iJwzekGMTRvap84NYGhvpPzZH7mGe4p0ncNLonqxwG8isSDzPr7-KpZPADHlrKgSIvjM6MK3QN-pldcjYKopVflHvsrQFw6eE-GhrhXPnA8VvgnPp68u17AJi1RHQsSn8_GRAQLZD/s1600/Snap4.png" /></a></div>
</li>
</ol>
<div class="separator" style="clear: both; text-align: center;">
</div>
Notice that the "<span style="font-family: "courier new" , "courier" , monospace;">id</span>" attribute of the <span style="font-family: "courier new" , "courier" , monospace;"><div></span> element is the same as the <span style="font-family: "courier new" , "courier" , monospace;">#</span> name that I gave in my <span style="font-family: "courier new" , "courier" , monospace;"><script></span> tag.<br />
Notice also that the <span style="font-family: "courier new" , "courier" , monospace;"><div></span> tag has no content and looks like an empty tag. But, when the file is rendered in a browser, the actual contents of the file linked to that <span style="font-family: "courier new" , "courier" , monospace;"><div></span> element will be shown in this <span style="font-family: "courier new" , "courier" , monospace;"><div></span>.<br />
<br />
This content referencing works perfectly off a server (such as a GitHub content repo) but not in a local file system, so if you're trying this out on your laptop, 8 times out of 10, this won't work. You'll need to test it on a server. I don't know why it works 2 times out of 10.<br />
<br />
Let me also talk about folder structure. To maintain our sanity, instead of having just one folder that contains all of the files, I created several folders: each folder holds only one kind of content. I thought it would be more intuitive for a multi-author environment. I also assumed that Udaan would continue to live, and that one day someone else might be managing these files, so I created a README file that explains the folder structure, and how the files inside these folders link to each other (for example, what is file X in folder Y doing here).<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiMud5aRbzLIStJlbHEp9rcqmGrz29lqq69aqCwghZVYqMmGC2y3ZDqYIQ25NBMSSErDVGaavgpmr5wH7gLKSRd7dglZyU0zdgkyR5xL4nxzrzTp3gbw62bl4nbplkbEyRLtftfw2lXp5B_/s1600/Snap1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiMud5aRbzLIStJlbHEp9rcqmGrz29lqq69aqCwghZVYqMmGC2y3ZDqYIQ25NBMSSErDVGaavgpmr5wH7gLKSRd7dglZyU0zdgkyR5xL4nxzrzTp3gbw62bl4nbplkbEyRLtftfw2lXp5B_/s1600/Snap1.png" /></a></div>
<br />
Which brings me to premissions. Only the editors (Nibu Thomas and I) have write permission to the GitHub project. Because I own the project, I can add others to it, and adding such people will automatically give them write permission. Everyone else has read permission, which is the default GitHub permission for the whole world. If Udaan is managed by someone else in future, I can "transfer" the project (and, thus, ownership) to that person. The files still remain where they are, the Udaan articles still continue to be read by the world.<br />
<br />
People with read permission cannot directly modify the files but they can still file bugs. So, we asked all authors to review their own articles and also do peer-review, and open bug reports for all their suggested changes. By doing this, we broke free of email-jail. Everything pertaining to Udaan was captured right there, in the Udaan repo bugtracker, open for the whole world to see.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhDhWed0bnwtTa1g7i3vwHsi0Mg7iUfpjTjVHiXLks4uwmkwwj5m3UFSVpk_2O1c_M8RjsjgIW3epFlfNQwPdaMHlX5pkZqXYhx1EN0vKPojTFJkFQJg0RsuxGZtyMUHolGROGih1y2Mpe_/s1600/Snap5.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhDhWed0bnwtTa1g7i3vwHsi0Mg7iUfpjTjVHiXLks4uwmkwwj5m3UFSVpk_2O1c_M8RjsjgIW3epFlfNQwPdaMHlX5pkZqXYhx1EN0vKPojTFJkFQJg0RsuxGZtyMUHolGROGih1y2Mpe_/s320/Snap5.png" width="293" /></a></div>
<br />
I used GitHub's internal publishing method, so it's really a one-click thing. The moment you push a change into the publish-branch of the repo, that very moment the public URL is refreshed with the changed content. So, what's a publish branch? Well, in a GitHub repo, you can have several branches (which correspond to "streams" or "forks" in other repo parlance) but only the stuff that you put in a branch called "gh-pages" is the stuff that GitHub will publish to that external URL it gave you. It's somewhat like the DITA authoring scene: you can have a thousand files in a hundred folders but only those files that you put in a <span style="font-family: "courier new" , "courier" , monospace;">.ditamap</span> file are the ones that get published.<br />
<br />
Which brings me to the published web pages. For starters, I wanted the Udaan web page to "look" different from other open browser tags, so I used a favicon.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwhKTuNatIi3Zc0vZaZ0MBReXCidBqhbfJyY661y6-tm1CD9cPGxCTdaV86uFF5YQF2Um0jLWkKjYftBQXak9TG-hfKE-pW7fEAUUevoQw4AV_teSJbNPXS7d5oBcOEtFqcPvBof6uUIgw/s1600/Snap6.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="41" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwhKTuNatIi3Zc0vZaZ0MBReXCidBqhbfJyY661y6-tm1CD9cPGxCTdaV86uFF5YQF2Um0jLWkKjYftBQXak9TG-hfKE-pW7fEAUUevoQw4AV_teSJbNPXS7d5oBcOEtFqcPvBof6uUIgw/s640/Snap6.png" width="640" /></a></div>
<br />
You see tiny Michi on the Udaan tab? That's what we call a favicon. I couldn't get the favicon to show up in Chrome or IE. I scoured the net for a solution and tried every suggestion but nothing worked. If you know of a way, let me know. Meanwhile, here are the steps to get a favicon on a Firefox tab:<br />
<ol>
<li>Choose an image file that's no larger than 16 x 16 pixels.</li>
<li>Convert it to an <span style="font-family: "courier new" , "courier" , monospace;">.ico</span> file. There are several google-able online free services that'll do this in a trice.</li>
<li>Save the favicon in the root folder. Ideally, name the file <span style="font-family: "courier new" , "courier" , monospace;">favicon.ico</span>.</li>
<li>In all of the files, in the <span style="font-family: "courier new" , "courier" , monospace;"><head></span> section, add a link to the favicon file, like this:<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9vL1KJb2zDkfGjd2ssb4QmfvdT6HzrKhtLRfPRRVJZiYos67EyJUpaR-WqjvPgsbgcM3ewnEAc6mg9dI3oLFR0wdhPvFUDgePS37w_QSxjDP3Qr1hoCVkLVtJ5jOC0UMeJ6TK3dVD2YrX/s1600/Snap9.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="36" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9vL1KJb2zDkfGjd2ssb4QmfvdT6HzrKhtLRfPRRVJZiYos67EyJUpaR-WqjvPgsbgcM3ewnEAc6mg9dI3oLFR0wdhPvFUDgePS37w_QSxjDP3Qr1hoCVkLVtJ5jOC0UMeJ6TK3dVD2YrX/s400/Snap9.png" width="400" /></a></div>
</li>
</ol>
<br />
After the browser tab, the actual content. I thought we should apply all the good-technical-writing stuff we know, so here's what Udaan has:<br />
<ul>
<li>The first paragraph, just after the title and author name, is either a summary of the entire article or a teaser to entice someone to read further. This is not only good SEO but akin to the <span style="font-family: "courier new" , "courier" , monospace;"><shortdesc></span> tag of DITA that everyone keeps telling me is good writing.<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjbjOqj46JGSuaveLT1OJ_3e9gqcTbk9OUlZyLZ6HHnLvVKGQe61sNjdND9Og9l3HEEu2vTGolN65S5sqqBvyzFRDEya5mq3duw_bPzjPWtFa3sR2yW-xZT9VMuQUJBoycj-7G1_o3riWnl/s1600/Snap7.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="143" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjbjOqj46JGSuaveLT1OJ_3e9gqcTbk9OUlZyLZ6HHnLvVKGQe61sNjdND9Og9l3HEEu2vTGolN65S5sqqBvyzFRDEya5mq3duw_bPzjPWtFa3sR2yW-xZT9VMuQUJBoycj-7G1_o3riWnl/s320/Snap7.png" width="320" /></a></div>
</li>
<li>This first paragraph is tweetable on click. The code is:<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9wtElFwZh1knk1aoqT6D1-c3oKiCiZ1t9UHsmq2nl8RAK3Z8d22a7ptY0ZBwtkarYZfZ7KdS3F4PcezcC0cJ6FFLkcmsywnKREa7_-7XCX3iNXWUmZdiaFuIbo29xNWNgE2nCHPBl8EQk/s1600/Snap8.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="57" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9wtElFwZh1knk1aoqT6D1-c3oKiCiZ1t9UHsmq2nl8RAK3Z8d22a7ptY0ZBwtkarYZfZ7KdS3F4PcezcC0cJ6FFLkcmsywnKREa7_-7XCX3iNXWUmZdiaFuIbo29xNWNgE2nCHPBl8EQk/s640/Snap8.png" width="640" /></a></div>
Notice the "<span style="font-family: "courier new" , "courier" , monospace;">href</span>" attribute. The first part, <span style="font-family: "courier new" , "courier" , monospace;">https://twitter.com/intent/tweet?</span>, is what makes a Twitter box pop up. The next part, <span style="font-family: "courier new" , "courier" , monospace;">text = ...whatever...</span>, is what auto-populates the Twitter box. Notice also that all non-text, non-comma, and non-period characters are represented by their ASCII symbols. Thus, a space is represented by <span style="font-family: "courier new" , "courier" , monospace;">%20</span>. Want to try out such clickable sentences in your semi-formal documentation such as customer-facing blogs?
</li>
<li>No page is an "orphan". Every Udaan article links to some other related article.</li>
<li>Every page is page one, so each article is complete in itself, with full header, footer, author details, content, acknowledgement, references, related links, and a ToC. </li>
<li>Progressive disclosure techniques were applied. You don't need to leave the page to read stuff like author profile (shown on mouseover) or to listen to audiocasts and watch video versions (shown within popup boxes). Footnote text is revealed on mouseover, so you don't have to jump back and forth on the page. Every link has a tooltip that shows the first sentence (the summary or teaser sentence) of that article, so you can decide before you click whether to go to that article. (To see all of these together on one page, see <a href="http://udaanstc.github.io/GutsAndGlory/html/asha.html" target="_blank">Asha Mokashi's leadership article</a>.)</li>
<li>Every page has a unique <span style="font-family: "courier new" , "courier" , monospace;"><title></span> tag (which won't be rendered on the browser page but is anyway picked up by search engines).</li>
<li>Every URL has descriptive link text.</li>
<li>For universal accessibility, we included voice versions. You are no longer tied down to a read-the-text scenario.</li>
<li>Voice interviews have the transcripts included, so you can read them if you don't want to listen in.</li>
</ul>
A word about the multimedia. The audio files are playable on click, achieved by using the embedded player feature of HTML5. The code is:<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEis1ejWAZgiFJjkqNoahUT3gVyMrbXLojdGhxtWq4hrt__Vj7O1NLVXNb9VUVcikh8DBI5ngLfiX3dhUVick1tXteGEDJXUHHABH673-FjDsfByqHlU7wj4bhUKSpWKoMf1uBEC7gX8cyGA/s1600/Snap10.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="30" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEis1ejWAZgiFJjkqNoahUT3gVyMrbXLojdGhxtWq4hrt__Vj7O1NLVXNb9VUVcikh8DBI5ngLfiX3dhUVick1tXteGEDJXUHHABH673-FjDsfByqHlU7wj4bhUKSpWKoMf1uBEC7gX8cyGA/s640/Snap10.png" width="640" /></a></div>
<br />
Notice the <span style="font-family: "courier new" , "courier" , monospace;">"control"</span> attribute of the <span style="font-family: "courier new" , "courier" , monospace;"><audio></span> tag. That's what specifies whether the player controls like Play and Pause should be displayed. Notice also text within the the <span style="font-family: "courier new" , "courier" , monospace;"><audio></span> tag. That's what's displayed if a browser cannot handle multimedia. I used words that describe what's gone wrong and what could be a possible solution.<br />
<br />
Udaan was to live online and its pages had several links. To eliminate broken links, I used Xenu link sleuth. I tried making a custom 404 page but discovered that's possible only with paid GitHub. Since the entire purpose of using Xenu was to eliminate a 404 scenario, this didn't bother me much.<br />
<br />
So much for the web version. Let me move on to the <span style="font-family: "courier new" , "courier" , monospace;">.epub</span> and <span style="font-family: "courier new" , "courier" , monospace;">.azw</span> versions, to be used on iPads and Kindles.<br />
<br />
I used Sigil to create an EPUB file. I imported the HTML files into Sigil, and generated the EPUB output. I then imported this EPUB into Calibre and generated an AZW file.<br />
<br />
This part took longer than I expected. An EPUB file is just an archive file (just like a <span style="font-family: "courier new" , "courier" , monospace;">.zip</span> file is) that contains XHTML for the basic content, and some other folders and files that tell computers that this is an EPUB file. The folder structure is fixed, and Sigil generates them for you.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEilA_OGbHIqaFnQXwreYlVYvVLFPzurDe7pLOz5z4m51h5JBpE7B1mjItEVz4A6_Ov3q9WHClLiHk6_8vQ1au_8XQFenWy7Q0czDvJF08OmLUnXYPsRGPhhZN9gN0NPa6IC_kHBmwhfHEPs/s1600/Snap13.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEilA_OGbHIqaFnQXwreYlVYvVLFPzurDe7pLOz5z4m51h5JBpE7B1mjItEVz4A6_Ov3q9WHClLiHk6_8vQ1au_8XQFenWy7Q0czDvJF08OmLUnXYPsRGPhhZN9gN0NPa6IC_kHBmwhfHEPs/s1600/Snap13.png" /></a></div>
<br />
All you need to do is put your content in the appropriate folders: audio, images, styles, and text. If I was embedding a video clip, there would've been another folder named "Video".<br />
<br />
The difficult part was the styling. I discovered that the CSS that looks great on a laptop looks awful in an e-reader. The task of manually stripping the HTML tags of all styling took about 2 hours. (This is where I miss DITA). I created a CSS file just for the EPUB, and specified some very basic styling such as line spacing and a background colour for headings. The rest of the output is the default HTML style. The end result might look plain on a computer screen but looks clean and neat on iPads and Kindles. <br />
<br />
For the audio, I used Audacity. Thanks are due to these people: Prachi Karnik, Deval Faldu, Santosh Krishnamurthy, Mihir Mishra, Mayuri Baruah, and Jolein Vadhariya; they gave their time to record someone else's articles. Another instance of giving back to the community. After the sound bytes were recorded, I discovered they'd been done in various file formats, so I first used Audacity to convert them to <span style="font-family: "courier new" , "courier" , monospace;">.mp3</span>. Then I googled for <a href="https://www.youtube.com/watch?v=NSssHrq9CNg" target="_blank">how to filter out background noise</a>,<a href="http://www.howtogeek.com/56264/the-how-to-geek-guide-to-audio-editing-cutting-trimming-arranging/" target="_blank"> how to trim the too long silences</a>, and <a href="http://manual.audacityteam.org/o/man/amplify.html" target="_blank">how to amplify the quiet bits</a>. The sound files still lack that "professional" feel but I think they serve our purpose fine.<br />
<br />
And Udaan was ready to be released.<br />
<br />
What didn't work well:<br />
<ul>
<li>The favicon. Like I said, I just couldn't get it to work on Chrome and IE. Also, I had to manually insert the favicon link in every HTML file; inserting it only in the boilerplate header file did not work.</li>
<li>The author profiles. I did a copy-paste from the home page to the individual articles. The content-referencing just did not work with the CSS I was using to show the profiles on mouseover. Maybe I need to create separate files for every author (in other words, maybe HTML content referencing works only for a *file* and not for an *anchor* within a file).</li>
<li>The multimedia in the EPUB file plays only with the iBooks app. I couldn't figure out a way to make it play with the default iPad reading app.</li>
<li>For the print version, there wasn't an easy way to port content from HTML to MS Publisher. Porting was done manually by Sangeeta Raghu Punnadi. Then, Nibu Thomas did the layout and inserted the sponsor ads and the fillers. It was not easy; "nightmare" was a word that was used several times. It also meant that content lived in two places: GitHub and Publisher. We couldn't figure out a way to create a "book" of discrete HTML files and turn that into a format that our print vendor could use. </li>
<li>I could not directly make an EPUB or AZW file from GitHub, which allows only HTML publishing, not other types of publishing. </li>
</ul>
What would've been nice to have but no time, no money, etc:<br />
<ul>
<li>A copybook-like underline style looks charming on iPads.<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEieez2Xk9Dy1ToGuRVouQDf_XFVadbxJg4zXZxu09-7jhfh__ZCr7DVkSCkWw4blmx-j9yv1ezgcQGQMkCNsxqsc62T1xhEjfqB6DXmw_FQGTi8Bjd9vLqAxLZeNXa9-iwdtG3f-lals3Yh/s1600/LandscapePageTurn.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="240" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEieez2Xk9Dy1ToGuRVouQDf_XFVadbxJg4zXZxu09-7jhfh__ZCr7DVkSCkWw4blmx-j9yv1ezgcQGQMkCNsxqsc62T1xhEjfqB6DXmw_FQGTi8Bjd9vLqAxLZeNXa9-iwdtG3f-lals3Yh/s320/LandscapePageTurn.jpg" width="320" /></a></div>
</li>
<li>The print version could also have had some interactivity. For example, think of Anagha's article on commonly-confused words. Now, think of a book page where you first read the tip, then lift a flap to see a cartoon underneath on the very same page.<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiVhjI7iSm8fqI-bkVr-lo2ghWHNDCdxfHT1CnPCs83xjukU7wTicLEEKAjwnfBsIRaw4OAHzPrxDuBKFpEmjR0Y5jiGCu2t9Iinjv0fIVjANrBS-kcW-LKu3Ir4Jh2MXvPSfrFhduZBUAE/s1600/Bartisch+Eye.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiVhjI7iSm8fqI-bkVr-lo2ghWHNDCdxfHT1CnPCs83xjukU7wTicLEEKAjwnfBsIRaw4OAHzPrxDuBKFpEmjR0Y5jiGCu2t9Iinjv0fIVjANrBS-kcW-LKu3Ir4Jh2MXvPSfrFhduZBUAE/s320/Bartisch+Eye.png" width="278" /></a></div>
</li>
<li>The print version could've had perforated pages for the blank pages (where you could've taken notes during the conference) and for the checklists in Rajib's leadership article (which you could've tacked to your workdesk for ready reference). </li>
</ul>
What software was used:<br />
<ul>
<li><a href="http://www.pnotepad.org/" target="_blank">Programmer's Notepad 2</a> for creating and editing the HTML, CSS, and JS files.</li>
<li><a href="https://desktop.github.com/" target="_blank">GitHub client for Windows desktop</a> to push the folder structure and non-text content into the GitHub repo. For text content, GitHub's web interface can be used (client not needed).</li>
<li><a href="http://audacityteam.org/" target="_blank">Audacity</a>, for editing the soundtracks and converting them to MP3.</li>
<li><a href="https://code.google.com/p/sigil/" target="_blank">Sigil</a>, for creating an EPUB file.</li>
<li><a href="http://calibre-ebook.com/" target="_blank">Calibre</a>, for converting an EPUB file to an AZW file.</li>
<li>Sound Recorder, Voice Recorder, or whatever it is that your computer or phone uses to record voice.</li>
<li>MS Paint, for making flowchart diagrams and for resizing pictures.</li>
<li><a href="http://home.snafu.de/tilman/xenulink.html" target="_blank">Xenu link sleuth</a>, for checking for broken links </li>
<li>For everything else, online resources:<ul>
<li>The comic strips were created at <a href="https://www.bitstrips.com/create/comic/" target="_blank">https://www.bitstrips.com/create/comic/</a> and <a href="http://www.makebeliefscomix.com/" target="_blank">http://www.makebeliefscomix.com/</a></li>
<li>The transparent background for the favicon was created at <a href="http://www.online-image-editor.com/help/transparency" target="_blank">http://www.online-image-editor.com/help/transparency</a></li>
<li>The PNG file of Michi was converted to ICO at <a href="http://convertico.com/" target="_blank">http://convertico.com/</a></li>
</ul>
</li>
</ul>
<br />
Which free CSS and JS files were used:<br />
<ul>
<li>The look and feel is because of w3.css and the related theme files of <a href="http://www.w3schools.com/w3css/default.asp" target="_blank">http://www.w3schools.com/w3css/default.asp</a>.</li>
<li>The flip-card effect is courtesy <a href="https://www.developphp.com/video/CSS/Flip-3D-Boxes-and-Cards-Animation-CSS-Tutorial" target="_blank">https://www.developphp.com/video/CSS/Flip-3D-Boxes-and-Cards-Animation-CSS-Tutorial</a>.</li>
<li>The javascript for footnotes-on-hover is from <a href="http://ignorethecode.net/blog/2010/04/20/footnotes/" target="_blank">http://ignorethecode.net/blog/2010/04/20/footnotes/</a>.</li>
<li>The scroll-to-top button is from <a href="http://www.scrolltotop.com/" target="_blank">http://www.scrolltotop.com/</a>.</li>
<li>The icons are from Google's material design icon library at <a href="https://www.google.com/design/icons/" target="_blank">https://www.google.com/design/icons/</a>.</li>
<li>The speech bubble styling is based on the CSS file from <a href="http://nicolasgallagher.com/pure-css-speech-bubbles/demo/" target="_blank">http://nicolasgallagher.com/pure-css-speech-bubbles/demo/</a>.</li>
<li>The styling on mouseover is based on the CSS file from <a href="http://www.menucool.com/tooltip/css-tooltip/" target="_blank">http://www.menucool.com/tooltip/css-tooltip</a>.</li>
<li>The commenting facility is courtesy <a href="http://web.livefyre.com/comments/" target="_blank">http://web.livefyre.com/comments/</a>.</li>
</ul>
So, yeah, that's the Udaan back-end story. The entire source code of Udaan is on this GitHub repo: <a href="https://github.com/UdaanSTC/GutsAndGlory/tree/gh-pages" target="_blank">https://github.com/UdaanSTC/GutsAndGlory/tree/gh-pages</a>.<br />
<br />
And Udaan itself is here: <a href="http://udaanstc.github.io/GutsAndGlory/index.html" target="_blank">Udaan</a>.<br />
<br />
Here's what Udaan Print looks like: 100 pages, A5, hardbound, all colour. Distributed to the 350-odd people who came to the conference.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgCNQfiVdeEL57MGWnvztTOiiLTrBaWPLPGEoB-29WsUkEkHJgZZPQcybt6kb3F05W9DcF-Nnw5cDYzO1Sl_eBI4TL8NwGNMEskcPjr38OPkua_9ZMLPLDMEl_dzTZS1vHorWOt0qg0fTwI/s1600/DSCN0124.JPG" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgCNQfiVdeEL57MGWnvztTOiiLTrBaWPLPGEoB-29WsUkEkHJgZZPQcybt6kb3F05W9DcF-Nnw5cDYzO1Sl_eBI4TL8NwGNMEskcPjr38OPkua_9ZMLPLDMEl_dzTZS1vHorWOt0qg0fTwI/s320/DSCN0124.JPG" width="240" /></a></div>
<br />
<br />
<br />
To see a 3-minute video on the Udaan story, see this:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<iframe allowfullscreen="" class="YOUTUBE-iframe-video" data-thumbnail-src="https://i.ytimg.com/vi/ukoPAxHiXTg/0.jpg" frameborder="0" height="266" src="https://www.youtube.com/embed/ukoPAxHiXTg?feature=player_embedded" width="320"></iframe></div>
<br />
<br />
<hr />
<span style="font-size: x-small;">* iBooks EPUB picture is from <a href="https://www.ibm.com/developerworks/community/blogs/aimsupport/entry/cics_transaction_server_now_has_epub?lang=en" target="_blank">https://www.ibm.com/developerworks/community/blogs/aimsupport/entry/cics_transaction_server_now_has_epub?lang=en</a> </span><br />
<span style="font-size: x-small;">** flap-in-book picture is from <a href="http://www.booktryst.com/2011/04/anatomy-gets-animated-in-rare-flap.html" target="_blank">http://www.booktryst.com/2011/04/anatomy-gets-animated-in-rare-flap.html</a> </span>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com2tag:blogger.com,1999:blog-1520346663771309945.post-21532048642301002022011-12-07T01:51:00.002+05:302011-12-07T23:18:51.235+05:30Techwriting lessons from films<div style="font-family: "Courier New",Courier,monospace;"><span style="font-size: small;">This post contains what I presented at the STC India annual conference of 2011 at Chennai.</span></div><hr />We'll go straight to the first of the film clips. [The videos might take a while to appear on the page. Depends upon the internet speed.]<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dzE8qtW3ccR8EcAxGHNiCySkTXdlRZYn0KlV5QXuifK_h5s_aHLv-_NQmxOAl4CCq6d9ojOQ-gxSS7GWfn_pw' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="color: #cc0000;"><span style="font-family: "Courier New",Courier,monospace;">When chess pieces go missing</span></b><span style="color: #cc0000;"> </span></div><br />
The lesson I learnt from this movie sequence? That I need to be more concerned about my <b style="color: #cc0000;">core skill</b> (writing) than the tools I am using to practice that skill. That, as a writer, my other core skills must be<b> </b>agility, resourcefulness, and adaptibility so that I can work with whatever is available to deliver that which is deadlined.<br />
<br />
On to the next lesson.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dxQfiDv2Ssz0zduaLIu7q_HgbGLyTrY7zrRdqxBcbvI8EcX1ui0DeZVhxNAqhBUPEwU9MiNSn8l3hdHPaMO3A' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="color: #cc0000;"><span style="font-family: "Courier New",Courier,monospace;">You have to ask me nicely</span></b><span style="color: #cc0000;"> </span></div><br />
As a writer, I am on cross-functional team meetings, I test software, I file defects, I coax people to share their knowledge…I need to know the people I am talking to. And, I need to ask them nicely. Because, I work with talking-feeling humans for:<br />
<ul><li>Getting information from the development teams</li>
<li>Getting the technical and editorial reviews done</li>
<li>Getting feedback from customer-facing teams</li>
<li>Getting support from the doc team</li>
</ul>Next clip.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dzeQNqDGM5C5rfNClzgqJ6UeegPaCVfjmgzOO56EHiNbtdqGCmuRW0xp6BHzug7-FYD2_kxjDUZdYDUyCnRew' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="color: #cc0000; font-family: "Courier New",Courier,monospace; text-align: center;"><b>Are my eyes really brown? </b></div><br />
My takeaway from that question was <b style="color: #cc0000;">Accuracy</b> - My writing must be free from mistakes, must adhere to facts. I must:<br />
<ul><li>Write only that information which you have understood and verified</li>
<li>Maintain consistency of all information about a subject</li>
</ul>On to my next lesson.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dxTSFH1wqxMrb9mixLeokgn1d_xoOQm8Fs8x5UWxksHqi9bvYX7TBJqqSj8nWEazCNziqlOgEfu8wrbOM_Zyw' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="color: #cc0000; font-family: "Courier New",Courier,monospace;">I'll speak real slow </b></div><br />
This one is about <b style="color: #cc0000;">Clarity</b>, about freedom from ambiguity or obfuscation, about presenting the information in such a manner that it can be understood the first time<br />
<br />
Here, let me show you a film sequence that demonstrates what is <b style="color: #cc0000;">not Clarity</b>.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dwrGsbhK-Qn-yXDqIMR-_ElZjHckMizYKTrY6DkD2kQwb9LPrRCX8ifyiV_H-3sRMq6Hyb7KhO8Z2guY1hQdQ' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="color: #cc0000; font-family: "Courier New",Courier,monospace;">I'll speak real slow </b></div><br />
Now, I'll show you a scene from a Sunny Deol movie.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dzsX7e1swkJBMfdN4AuVSyN4gNCTF85AXuOXjZCuyJ-C-FFFBMtlBuJOfVTVyMsH_Yw2Srzc6XcKNqpniBZuA' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="color: #cc0000; font-family: "Courier New",Courier,monospace;">Dropping down dead</b> </div><br />
Some docs are so heavy, trying to read them is like being hit by a ton of bricks. Docs that knock me down dead. The lesson I learnt from Sunny's killer punch is about<b> <span style="color: #cc0000;">Retrievability</span></b> and <b><span style="color: #cc0000;">Organisation</span></b>. About how my documents must:<br />
<ul><li>Provide helpful entry points </li>
<li>Facilitate navigation and search</li>
<li>Give an index</li>
<li>Provide you-are-here indicators</li>
<li>Suggest links to similar or related information</li>
</ul>Next on to my all-time favourite Kamal Hassan movie. No, I don't understand Tamil, the language that this movie is in but hey! this clip doesn't need me to know Tamil.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dwfcpED9pw-6uSkMfsbcMq1i_wRTPCcJCDG6CBRRkxbuNcqsLLTpocW_fXcemV5TMusvSs-aeN7LSb2J8isLA' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><b style="font-family: "Courier New",Courier,monospace;"><span style="color: #cc0000;">What language was that </span></b></div><br />
This one's about <b style="color: #cc0000;">Style</b>, about the correctness of writing conventions, and of words and phrases. What I learnt from this film sequence is that I must always:<br />
<ul><li>Use correct grammar, spelling, and punctuation</li>
<li>Follow template designs</li>
<li>Use boilerplate text</li>
<li>Follow style guidelines</li>
</ul>Here's the next clip.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dwPjTiPUJBwv7UndPVJieC4AlJAgeEsgUeMkfKIR9XiFjALHMKzWJErj4qSwbTNcqd5jwSuB1MnPMzUM8fQBA' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><span style="font-family: "Courier New",Courier,monospace;"><b><span style="color: #cc0000;">When you have to shoot, shoot</span></b></span> </div><br />
My lesson? <b style="color: #cc0000;">Task orientation</b>. I must focus on helping getting a job done. I must classify my information by its type so that I can:<br />
<ul><li>Create docs in a consistent manner, so that the right design gets used (for example, tables for reference information, step sequences for tasks)</li>
<li>Focus on tasks, and move the supporting concepts and reference information into other topics, where they can be read if required and ignored if not</li>
</ul>When my information is focussed on the task at hand, stripped of all supporting information, here's how I can help people get their jobs done.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dx76VtbqBBPtYA1L59SiYnXBWKjYonAt0jirL2nbPl82gtVKpoSFCgPEiQktBlSiAWuxbt2XCRLn6kZfxQgyQ' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><span style="font-family: "Courier New",Courier,monospace;"><b><span style="color: #cc0000;">When you have to shoot, shoot</span></b></span> </div><br />
And now to the last of the film clips.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen='allowfullscreen' webkitallowfullscreen='webkitallowfullscreen' mozallowfullscreen='mozallowfullscreen' width='320' height='266' src='https://www.blogger.com/video.g?token=AD6v5dw8kwd7Cx0gXB2ZmWIi_85hazinprVUe8PrU8mCq22_DcC8X00zUL1pXSUvAS6QDo-U4pkxM9deXZAF60S1pw' class='b-hbp-video b-uploaded' frameborder='0'></iframe></div><br />
<div style="text-align: center;"><span style="font-family: "Courier New",Courier,monospace;"><b><span style="color: #cc0000;">Broken bones</span></b></span> </div><br />
This one's about <b style="color: #cc0000;">Visual effectiveness</b>, about how I should:<br />
<ul><li>Ensure that all users can access the information</li>
<li>Use graphics to complement the text</li>
</ul><hr /><div style="font-family: "Courier New",Courier,monospace;"><span style="font-size: x-small;"><span style="font-family: "Courier New",Courier,monospace; font-size: small;"><b style="color: #cc0000;">Acknowledgements</b></span><span style="font-family: "Courier New",Courier,monospace;"> </span></span></div><ul style="font-family: "Courier New",Courier,monospace;"><li><span style="font-size: small;">Films: Shatranj Ke Khiladi, A Few Good Men, Casablanca, Deja Vu, Fandango, Damini, Salangai Oli, The Good The Bad The Ugly, Beverly Hills Cop, and Rear Window </span></li>
<li><span style="font-size: small;">Books: The IBM Press book called <a href="http://www.ibmpressbooks.com/bookstore/product.asp?isbn=0131477498" target="_blank">Developing Quality Technical Education</a></span></li>
</ul><ul></ul>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com6tag:blogger.com,1999:blog-1520346663771309945.post-77561551408909843292011-03-22T15:49:00.006+05:302011-03-25T16:58:06.504+05:30Recasting the recipeJust because I do something well does not necessarily mean I like doing it. Cooking, for example. Hence, I steer clear of all recipe booklets, cooking websites, and similar. But a weekend conversation on FaceBook about things planned for the Holi break needed me to sit down and write a recipe for my friend, fellow techwriter <a href="http://twitter.com/#!/samarthav">Samartha Vashishth</a>. One look at my mail and he wrote back saying "put in blog post" etc. Hence.<br />
<div style="text-align: center;"><span style="color: #990000; font-family: inherit; font-size: x-small;">I know the first list in that recipe should've been an unordered one. :-)</span></div><div style="text-align: center;"><span style="font-size: x-small;"><span style="color: #990000; font-family: inherit;">Let's take our edit hats off while we look at the recipe, shall we?</span> </span></div><br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhq0Dm2yJenSlOS0CDCfTH2GxeFM-wsgycaQysI372_-FUOcA31EqRlYna42CHbO-6guOyGD5coeeFpig_vPt8kWT9ptju4Uojo3eZm0PujeR4KEI-LFFeBDeIWNlM7dirlZbf99UhYAtDg/s1600/haleem.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="640" r6="true" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhq0Dm2yJenSlOS0CDCfTH2GxeFM-wsgycaQysI372_-FUOcA31EqRlYna42CHbO-6guOyGD5coeeFpig_vPt8kWT9ptju4Uojo3eZm0PujeR4KEI-LFFeBDeIWNlM7dirlZbf99UhYAtDg/s640/haleem.gif" width="492" /></a></div><div></div><div>How is it different from standard recipes? Here's how:</div><ul><li>It assumes you are doing only this task and nothing else. There's no "Do X and keep aside" instructions (despite possibilities); there's only a linear task flow.<br />
<span style="font-family: "Courier New", Courier, monospace;">Lesson for techcomm: Do not introduce branches into a procedure.</span></li>
<li>It does not just list the ingredients but group them according to when they're going to be used in the process and what they're going to be used together with. <br />
<span style="font-family: "Courier New", Courier, monospace;">Lesson for techcomm: Grouping of logically related items aids in (i) comprehension (ii) task completion.</span></li>
<li>It does not have pictures :) <br />
<span style="font-family: "Courier New", Courier, monospace;">Lesson for techcomm: Use pictures only if they are essential to performing the task.</span></li>
</ul>How I could've made it better? Listed the utensils, perhaps. No recipe that I've come across ever lists them (except, maybe, cakes, and that too a grudging <em>5" baking tray</em> mention) even though they are very important to the task at hand. Notice how, in step 9, I suddenly introduce a utensil (bharta toaster) that is otherwise not logically related to the cooking of haleem? Bad!Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com3tag:blogger.com,1999:blog-1520346663771309945.post-23135915115028447992011-03-09T14:41:00.002+05:302011-03-09T16:00:16.083+05:30Tweet, don't twitter"Talk rapidly and at length in a trivial way <span style="font-size: x-small;"><strong><span style="color: #990000;">*</span></strong> </span>" is what prompted this blog post. I've been on Twitter for close to two years now and thought it was time I compiled a "Thou shalt not" list for tweeting. So, here goes:<br />
<ol><li>Do not use "Pls RT". Not only does that use up six characters, it also presumes I am not smart enough to know if something is good enough to be shouted of from rooftops. That, and the fact I hate being told what to do.</li>
<li>Do not use up all 140 characters unless unavoidable. Leave enough room for your twitter handle (if someone wants to RT) and some comments (from people who're sharing your tweet). The first is self-promotion, the second is courtesy.</li>
<li>Do not tweet ONLY to share your blog post URLs. Thanks, but we have feed readers for that.</li>
<li>Do not keep retweeting like there's no tomorrow. If we are linked through Twitter, there's a 1 in 2 probablity that our Followed list is very similar. Retweets by you clog up my timeline. If you find yourself retweeting stuff too often, consider putting those tweets into paper.li and sending out ONE single paper.li-automated tweet daily. Besides, if all that you do is retweet, I am going to Unfollow you within a week (unless what I was looking for was a human feed-aggregator. For free).</li>
<li>Do not just retweet - tell me why you thought it was retweetable (see #2).</li>
<li>Do not be a radio commentator on the sports field. If I am as enthusiastic about that game as you, I am watching it (and not reading your tweets). If I hate sports, you're clogging up my timeline and, No, I can't filter you out because you never use hashtags and words consistently. This holds true not only of sports but of TV programs as well.</li>
<li>Do not tweet something that wouldn't make sense to 50% of your followers. What, you do not know about your followers? Bleh! You talking to chairs and tables, then - where's the point?</li>
<li>Do not tweet long updates one after the other, 16 tweets to a minute for 3 full minutes. If you have lots to say, use Twitlonger (or whatever) or write a blog post.</li>
</ol>As with life, so with Twitter - do not blabber and do know who you are talking to.<br />
<br />
<span style="color: #990000; font-size: x-small;">--------</span><br />
<span style="color: #990000; font-size: x-small;"><strong>* One of the definitions of 'twitter (verb)' given by the Oxford dictionary</strong></span><br />
<br />
Disclaimer: Sorry for the rant post but I just had to. Rant, i.e.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com6tag:blogger.com,1999:blog-1520346663771309945.post-73953485080313490332011-03-05T21:16:00.000+05:302011-03-05T21:16:59.786+05:30Listen! Do you want to know a secret?<blockquote style="color: #cc0000; font-family: "Courier New",Courier,monospace;"><blockquote><blockquote><strong style="font-weight: normal;">Let's start at the very beginning</strong><br />
<strong style="font-weight: normal;">A very good place to start</strong><br />
<strong style="font-weight: normal;">When you read, you begin with A-B-C</strong></blockquote></blockquote></blockquote><ul><li><strong>A</strong> is for Adobe. The company that left Anindita with the distinct impression that it thinks that that the techcomm world revolves around it. Also see <strong>F</strong> and <strong>R</strong>.</li>
<li><strong>B</strong> is for Beta. It stands neither for the second letter in the Greek alphabet nor the second brightest star in a constellation. It stands for not-yet-ready releases and is an excellent medium for techcommers to get feedback on their work.</li>
<li><strong>C</strong> is for content. That which makes the techcomm world go round.</li>
<li><strong>D</strong> is for DITA. That thing which cures all ills. Sane voices suggest otherwise but people still see through the glass darkly.</li>
<li><strong>E</strong> is for English. A language much maligned by a tiny, pint-sized apostrophe, which, if misaligned, can even become a comma. <strong>E</strong> is for editors. That group of people who are haplessly left with correcting the <em>that</em>s and <em>which</em>s when what they’d dearly like to do is spend time on indexes, navigation, and coherence and cohesion.</li>
<li><strong>F</strong> is for FrameMaker (See <strong>A</strong>). <strong>F</strong> is for feedback. A message where the message is often confused with the messenger, often unjustly.</li>
<li><strong>G</strong> is for Google. It is a help authoring tool that saves a lot of SME time (see <strong>S</strong>).</li>
<li><strong>H</strong> is for Help. A verb and a noun (See the possibility related <strong>V</strong>). Help is a privilege. You may want it but not get it.</li>
<li><strong>I</strong> is for information. Information is a noun that cannot stand on its own; it must always be used as an adjective. Information design, information architecture, information developer, and information overload, for instance.</li>
<li><strong>J</strong> is for coffee and pictures. As in, Java and JPEG.</li>
<li><strong>K</strong> is for knowledge. Of, besides writing, the tools, domains, and processes.</li>
<li><strong>L</strong> is for listening. It stands for the characteristic of being alert and ready to hear anything that might lead to knowledge (see <strong>K</strong>).</li>
<li><strong>M</strong> is for multimedia, an umbrella term for anything that moves, creates noise, and can be packaged.</li>
<li><strong>N</strong> is for No. As in, “No, I will not document how it should work; only, how it does indeed work”, “No, I will not put this screenshot here because …”, “No, this will not go into an install guide because….”</li>
<li><strong>O</strong> is for obfuscation. So long as obfuscation exists, so will a technical communicator. If you do not know what obfuscation is, here is an example: <em>“The relationship, which I might tentatively venture to aver has not been without a degree of reciprocal utility and even perhaps occasional gratification, is approaching the point of irreversible bifurcation and, to put it briefly, is in the propinquity of its ultimate regrettable termination.”</em></li>
<li><strong>P</strong> is for PDF. It was born in 1993. Other births that year include Microsoft Windows NT and the republics of Slovakia and Czech.</li>
<li><strong>Q</strong> is for curiosity. Why should I…? How does this…? When will it…? If I do this, what will….? What’s the difference between…? What is the weight of the moon?</li>
<li><strong>R</strong> is for RoboHelp (See <strong>A</strong>). <strong>R</strong> is for respect. An emotion that causes much existential angst among techcommers.</li>
<li><strong>S</strong> is for scrum. It means giving daily updates to your team and then running back to do the work you yourself promised to. <strong>S</strong> is for SME. It means the fount of knowledge from which information must be gleaned. <strong>S</strong> is for substance (See <strong>C</strong>)<strong>.</strong> <strong>S</strong> is for style. It is something best only followed, not tampered with.</li>
<li><strong>T</strong> is for Twitter. A medium used almost exclusively to pimp blog posts, product launches, and rave reviews. <strong>T</strong> is for TWIN. Bonded for life.</li>
<li><strong>U</strong> is a letter so important that it must never be used in isolation. <strong>U</strong> is royalty and must always be teamed with other letters, like this: UX, UA. <strong>U</strong> is the reason techcommers exist; <strong>U</strong> is for users.</li>
<li><strong>V</strong> is for vision. That which makes techcommers put descriptions in alt text, pick the reds and greens with care, and prefer lists to tables. The ability to see beyond the obvious, to ‘write’ for everyone.</li>
<li><strong>W</strong> is for wiki. Everybody knows it’s there but nobody knows what to do with it, hoping that somebody comes up with a wiki-to-source roundtripping that helps anybody adopt a wiki.</li>
<li><strong>X</strong> is a placeholder. As in XML.</li>
<li><strong>Y</strong>. A letter for which I could not come up with a word. I did try to match it to words such as Yes, Year, Yearn, and Yesterday but felt something was missing. So, I am leaving Y alone. For You, the reader.</li>
<li><strong>Z</strong> is for zen. And the art of writing for motorcycle mechanics.</li>
</ul><blockquote><blockquote><blockquote><span style="color: #cc0000; font-family: "Courier New",Courier,monospace;">When you know the notes to sing</span><br style="color: #cc0000; font-family: "Courier New",Courier,monospace;" /><span style="color: #cc0000; font-family: "Courier New",Courier,monospace;">You can sing most anything</span> </blockquote></blockquote></blockquote><div style="text-align: center;">==================================================== </div><div style="color: #660000;"><span style="font-size: x-small;">This first appeared in the Nov-Dec2010 issue of INDUS, STC-India's newsletter.</span></div><br />
<br />
<div style="color: #660000;"><span style="font-size: x-small;"><strong>Acknowledgements</strong></span></div><ul style="color: #660000;"><li><span style="font-size: x-small;"><em>Rachna Singh Ganguli for G = Google, F = feedback, Help is a privilege, J=Java and JPEG, R = respect; T=TWIN.</em></span></li>
<li><span style="font-size: x-small;"><em>Anagha Bhat-Chandratrey for K = knowledge, L = learning.</em></span></li>
<li><span style="font-size: x-small;"><em>The Beatles, for “Listen! Do you want to know a secret”.</em></span></li>
<li><span style="font-size: x-small;"><em>The people of The Sound of Music (1965) for “Let’s start…with A-B-C” and “When you know…most anything”.</em></span></li>
<li><span style="font-size: x-small;"><em>The people of Yes, Minister (BBC) for “The relationship…termination”.</em></span></li>
</ul>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com3tag:blogger.com,1999:blog-1520346663771309945.post-68572683856146706832011-02-18T09:24:00.002+05:302011-02-18T12:24:09.750+05:30Woo hoo! Smart search is possibleWatson had not been on my mind when I wrote my last blog post. In fact, if you were to shake me awake in the middle of the night and say, "Watson!", my immediate response would have been "Elementary, Holmes!" Despite being vaguely aware of a project called Watson underway in my company, the name didn't really mean "Wow" to me till, well, last night. But before I tell you why, let me go back a bit - and talk about my last blog post. In that post, I had implied 'storage' and 'retrieval' are two different things and, while tagging and indexing might work when one is storing something, the same tag or index could fail while retrieving the data. In my post, I had put foward a question - should content be context insensitive for it to be reused effectively? Conventional wisdom - that which runs search engines and SEO jobs - says, "No".<br />
<br />
And then came along Watson, and beat two people in Jeopardy to win an indecent amount of money, which, it was declared, would be given to charity. A computer beat two awesome humans.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><object class="BLOGGER-youtube-video" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,40,0" data-thumbnail-src="http://0.gvt0.com/vi/lI-M7O_bRNg/0.jpg" height="266" width="320"><param name="movie" value="http://www.youtube.com/v/lI-M7O_bRNg&fs=1&source=uds" /><param name="bgcolor" value="#FFFFFF" /><embed width="320" height="266" src="http://www.youtube.com/v/lI-M7O_bRNg&fs=1&source=uds" type="application/x-shockwave-flash"></embed></object></div><div style="border-bottom: medium none; border-left: medium none; border-right: medium none; border-top: medium none;"><br />
</div><div style="border-bottom: medium none; border-left: medium none; border-right: medium none; border-top: medium none;">Somewhere halfway through this video, when analysing why Watson got 'Chicago' wrong, you'll see the IBM engineer say something like "the info was stored in sectors but this was not about discrete compartments" or something to that effect.</div><div style="border-bottom: medium none; border-left: medium none; border-right: medium none; border-top: medium none;"><br />
</div>Exactly! Human brain does not process information in linear paths. It hops, skips, jumps, runs around in circles. And, because we're getting there - with Watson's help - I think in my lifetime at least I'll see content being reused in ways that I (the writer) never imagined it could be because the user (with help from Watson) is retrieving just that much - and only that much - information that the user needs. Correctly, every time, the first time. Smart user!Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-51229753838473515112011-02-10T13:34:00.006+05:302011-02-18T12:24:24.384+05:30Lose that tag pleaseIt all started last night when I tweeted some Hindi film dialogues (In India, we have two major religions - films and cricket).<br />
<div align="center"><span style="color: #660000; font-family: "Trebuchet MS", sans-serif; font-size: xx-small;">(to zoom, click the image)</span></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEimA953LkZPFjO2wn9Odo1khVAAJ-lRaNTzhn6Bz16UIX3pmS75lT4cq2L1zBIeZ2IzBgMR1r3EX7o9hXrUEu-ke4yeRXvuke_pVEmPmt7jHthTJNBvID0tliVh2kA21LIzJI7yhWbwlLJj/s1600/Snap1.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" h5="true" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEimA953LkZPFjO2wn9Odo1khVAAJ-lRaNTzhn6Bz16UIX3pmS75lT4cq2L1zBIeZ2IzBgMR1r3EX7o9hXrUEu-ke4yeRXvuke_pVEmPmt7jHthTJNBvID0tliVh2kA21LIzJI7yhWbwlLJj/s320/Snap1.gif" width="245" /></a></div>And then, we got around to discussing the bestest comedy film that's ever come out of Bombay. And, this was the tweet that got me to writing this blog post.<br />
<div style="text-align: center;"><span style="color: #660000; font-family: "Trebuchet MS", sans-serif; font-size: xx-small;">(to zoom, click the image)</span></div><div style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgdZo_c_DcOBlgGBFEruVFCF5MC_PpK9cx5WXLh7zwbsLRBrFnyZ-Cgutq7pijSCavFmoIhubdU4O3GZ5Z0EOv3ga2Y4h9UeadmCt3gNcssHRtF_Zm1phJZLiicvT7v4ITG-HS52MqIRg2D/s1600/Snap2.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" h5="true" height="134" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgdZo_c_DcOBlgGBFEruVFCF5MC_PpK9cx5WXLh7zwbsLRBrFnyZ-Cgutq7pijSCavFmoIhubdU4O3GZ5Z0EOv3ga2Y4h9UeadmCt3gNcssHRtF_Zm1phJZLiicvT7v4ITG-HS52MqIRg2D/s320/Snap2.gif" width="320" /></a></div>How is this relevant to techwriting?<br />
<br />
Well, if I were an indexer, I'd have probably tagged all my film content with some of these words: bombay, bollywood, hindifilm, <nameOFfilm><nameoffilm>, <nameOFstar><nameofstar>, and so on? Very search friendly and all. But say, my reader was a sociologist researching corruption in India (ahem!). This dialogue ("Thoda khao, thoda phenko" #epic) would never even show up in the search results, yet it contains exactly what the sociologist is looking for - the entire social mileu from which the phenomenon has sprung (including the defence mechanisms people employ to forget the misery it produces).<br />
<br />
So, how did I link this dialogue to scams (that are occupying the entire front page - and more - of newspapers these past weeks)? Because in my mind, my content database is neither indexed nor tagged. I can pull out random references and tag it to anything random and yet make it look relevant.<br />
<blockquote><span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Me</b>: To copy, perchance to paste; Aye, there's the rub for in that paste what copies might come when we have shuffled the platforms and the versions out of the filters.</span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Colleague</b>: Coils. Not filters. Coils.</span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Me</b>: Coils.</span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><silence for one minute></span><span style="font-family: "Courier New", Courier, monospace;"><br />
<span style="color: #660000;"></span></span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Colleague</b>: A coil is a wrapper, right?</span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Me</b>: Right.</span><br />
<span style="color: #660000; font-family: "Courier New", Courier, monospace;"><b>Colleague</b>: So, if we put a wrapper to call the boolean....</span></blockquote>So, here I am, thinking if there is more to indexing that meets the eye. More to content reuse? More to "context"? Thoughts?Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com1tag:blogger.com,1999:blog-1520346663771309945.post-85417658543178443222011-01-22T15:48:00.002+05:302011-01-26T19:25:36.677+05:30Where is the User in the DesignCreation and delivery of help content was what was on my mind as I sat crocheting a tiny coin purse for my mother. She has a very cute, 3-inch, pot-bellied leather purse that she uses to keep her loose change in but it's coming apart at the seams, hence I sat there, crocheting this:<br />
<div style="text-align: center;"><span style="color: #660000;"><span style="font-size: x-small;"><span style="font-family: "Trebuchet MS", sans-serif;">To zoom in, click on the picture</span></span></span> </div><div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9vc2JpA9pe5eTSFYCmkv2pVezyr4nMWDWQQjmSQ8ZuDqoK_eHZ5Mw6lUmvyA_K20LFHbTYnfNXI8asUUndHm_HMjeCSnsEbJM2fx2wA4moS_SFo2y9oUXrZ_u3Ik0hVkpHzc730oE-vWl/s1600/purse_ma.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" s5="true" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi9vc2JpA9pe5eTSFYCmkv2pVezyr4nMWDWQQjmSQ8ZuDqoK_eHZ5Mw6lUmvyA_K20LFHbTYnfNXI8asUUndHm_HMjeCSnsEbJM2fx2wA4moS_SFo2y9oUXrZ_u3Ik0hVkpHzc730oE-vWl/s1600/purse_ma.jpg" /></a></div><br />
And, have we not often come across something like this:<br />
<div style="text-align: center;"><span style="color: #660000;"><span style="font-size: x-small;"><span style="font-family: "Trebuchet MS", sans-serif;">To zoom in, click on the picture</span></span></span> </div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj8x790UUTufAMbh66CsNJogT7igZ0NZvociiehNv7XlxXceHiukaK5Fey136OJ0-1_xlcOmeD2c0KtlJD9aQVf0I0pirBZ5tsaj1Qw1BpGJL7WmtJ9RE2UhPfRsOTKDzi-kbJyK8R1-MOe/s1600/purse_cloud.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="187" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj8x790UUTufAMbh66CsNJogT7igZ0NZvociiehNv7XlxXceHiukaK5Fey136OJ0-1_xlcOmeD2c0KtlJD9aQVf0I0pirBZ5tsaj1Qw1BpGJL7WmtJ9RE2UhPfRsOTKDzi-kbJyK8R1-MOe/s320/purse_cloud.jpg" width="320" /></a></div><div align="center"><span style="font-family: "Trebuchet MS", sans-serif;"><span style="font-size: x-small;"><span style="color: #660000;">[Note: Thanks for catching the misplaced apostrophe. Feeling too lazy to edit the pic.</span>]</span></span></div><br />
I am picturing a scenario with me and my mom:<br />
<div style="text-align: center;"> <span style="color: #660000;"><span style="font-size: x-small;"><span style="font-family: "Trebuchet MS", sans-serif;">To zoom in, click on the picture</span></span></span></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh0m1zsLd55DucVvAivlFUtJRjlLqxpC3Py1pS2fgJOqfdjs1HRijMOQ9xnPVxMYD1gDvMGGCHHhLJvgGImxRPcdO9PplX0uGgoCvyriAxrlooUdqWYn3BhRbj34MMcxWoheOvV2Un9M0xX/s1600/purse_coins_where.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="141" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh0m1zsLd55DucVvAivlFUtJRjlLqxpC3Py1pS2fgJOqfdjs1HRijMOQ9xnPVxMYD1gDvMGGCHHhLJvgGImxRPcdO9PplX0uGgoCvyriAxrlooUdqWYn3BhRbj34MMcxWoheOvV2Un9M0xX/s320/purse_coins_where.jpg" width="320" /></a></div><br />
Creating and delivering help content is very similar to creating any other product. So, I ask myself, Where, How, and When is my reader going to need this information. If I can answer these three questions, the content I create will truly be User Assistance.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com3tag:blogger.com,1999:blog-1520346663771309945.post-82878784985749297082010-12-25T23:37:00.002+05:302011-01-22T15:57:31.223+05:30Where is the user in the guideYesterday, I got myself a new phone. Last time I had bought one, it was April 2004 - a time when cellphones here did not have built-in FM radios, internet support, multimedia messaging, and all such exciting features that are so much passé today. Consequently, it was a very celliterate me that held the phone gingerly and regarded its QWERTY keyboard with interest. And thence started my frustration. I could not figure out how to do any of those exciting features that all phones have nowadays (let's not blame the UI now. All UIs seem non-intuitive to first-time users).<br />
So, I reached for the user guide. A glance at the ToC, and I could not find answers to any of my three questions.<br />
<div style="text-align: center;"><span style="color: #660000;"><span style="font-family: "Trebuchet MS",sans-serif;"><span style="font-size: xx-small;">To magnify the picture, click on the picture</span></span></span></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjCr144cvWNOgnpR-OfGaa-V97rWlZjwTK8vCB8KeK6jsSGIAotTSJniBn6wBNrQsqM7bEiTQxGnjWz1Ki9nb7GMCjjRbbZJzwWVJNMG0q8iE_WyO1BXTkmj5tUs2HnXAeFACCjxFZSAFpX/s1600/phone_guide.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="299" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjCr144cvWNOgnpR-OfGaa-V97rWlZjwTK8vCB8KeK6jsSGIAotTSJniBn6wBNrQsqM7bEiTQxGnjWz1Ki9nb7GMCjjRbbZJzwWVJNMG0q8iE_WyO1BXTkmj5tUs2HnXAeFACCjxFZSAFpX/s400/phone_guide.jpg" width="400" /></a></div><br />
"So what", I told myself. "Just a 37 page booklet. I'll flip through it and will surely find something."<br />
<br />
Five minutes later, I threw the booklet away, powered my laptop on, asked Google, and found answers to all my questions:<br />
<ul><li>How do I transfer a photo taken on the phone to my laptop?</li>
<li>Where do I get the Missed Calls list?</li>
<li>How do I disable the keypad beeps?</li>
</ul>I see several things wrong with this user guide but the one thing that stands out prominently is - this guide is describing the features of the phone; it's not describing the tasks I, the user, do.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com5tag:blogger.com,1999:blog-1520346663771309945.post-906804254499791172010-12-12T22:49:00.000+05:302010-12-12T22:49:28.668+05:30Of currency notes and informationToday, I want to talk about currency notes. Indian currency notes, to be precise. Someone asked me, "How many languages are spoken in India?" Sighing with relief that the question was not the more usual "You all don't speak Indian?", I leaned over, pulled the wallet out from my pocket, extracted a 100-rupee note, flipped it over, counted something, and declared, "Fifteen officially. Not counting Hindi and English."<br />
<br />
Users find information in the most unlikely of places. Had I been a "normal" user, the kinds that a techwriter would have had in mind while documenting something, I'd have gone to the Constitution of India website and referred to Schedule 8 - the place that lists all official languages (22, actually, till date, not including English). If I didn't know that's where the official languages are listed, I'd have run a Google search (which, in turn, leads me to the Eighth Schedule anyway). But I am not a normal user - just like most users are not normal users. Most users get their information from places that the writer might never have dreamt of.<br />
<br />
The currency note designer, on the other hand, is very well aware of the implications of the panel that I referred to.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjMgDIrU4wZ41aP6XJccuXKkLBKLbWJl1MtlyEJUEGDgH7tt54nphSJsZGM0zU5A9ebZk6zPaBkQBZ3bK3gSVZ4v3ITK6fkhP54Q1QYKNW8VBLNSy9aGl_HjzO0zQQy_ugV6tJgyxb9AXjw/s1600/100_rupee_obverse.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="147" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjMgDIrU4wZ41aP6XJccuXKkLBKLbWJl1MtlyEJUEGDgH7tt54nphSJsZGM0zU5A9ebZk6zPaBkQBZ3bK3gSVZ4v3ITK6fkhP54Q1QYKNW8VBLNSy9aGl_HjzO0zQQy_ugV6tJgyxb9AXjw/s320/100_rupee_obverse.jpg" width="320" /></a></div><br />
It is intentional - it's been put there to remind people what a greatly diverse country we are. I should know. I used to be part of our currency presses once upon a time. We used to call it the <a href="http://www.rbi.org.in/currency/Rs100.html" style="color: blue;"><u>language panel</u></a>. It's almost - but not quite- an easter egg <span style="font-size: x-small;">*</span>.<br />
<br />
Which led me to wonder - do technical writers put easter eggs in their documents? I've not seen any but would love to know.<br />
============================<br />
<span style="font-size: x-small;">* More on easter eggs: <a href="http://en.wikipedia.org/wiki/Easter_egg_%28media%29" style="color: blue;">Wikipedia link</a></span>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com1tag:blogger.com,1999:blog-1520346663771309945.post-29377317328271517442010-09-23T19:41:00.001+05:302010-09-23T19:42:23.615+05:30Am writing a bookI am writing a book on DITA.<br />
<br />
Yes, there are, already, books on DITA. Why, then, am I writing one? Because:<br />
<ul><li>I think this book closes the gap between "what is DITA" and "how can I write in DITA".</li>
<li>I had wished for a book like this when I had started off with DITA.</li>
</ul><br />
XML Press is bringing the book out next year. Here's more on the book: <a href="http://xmlpress.net/publications/dita/authoring/" style="color: blue;"><u>Authoring with DITA</u></a>.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com6tag:blogger.com,1999:blog-1520346663771309945.post-39745905827805619812010-09-08T21:59:00.000+05:302010-09-08T21:59:18.592+05:30The Myth of the Holy CowIn my life as a technical writer, I have been handed out quite a few myths [A myth, says the Oxford dictionary, is a traditional story], myths that come disguised as commandments that resound with a Thou Shalt Not. The intention, I suspect, is to lull me to passive obedience. In this blog post, I will mention some of these myths and what I think (and do) about them.<br />
<br />
<div style="color: red;"><b>Passive voice has no place in technical writing</b></div>Before I state my position on this myth, let us recollect the definition of <i>voice</i>: the form of the verb that shows the relation of the subject to the action. So, the voice of a sentence shows whether the subject actively took ownership of an action and did it, or was so passive as to only be the recipient of the effects of the action.<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjDWfhmBas_gUKq-SBqewiONopReFgnxfyh4e8w0-64vchI23abTi_jc2E2MrWX1X8y_oUZ_svTxpa4ER_KIYYc-xdeGkLudinZomDiPGjSHZWgzcXJf2M_ylJI5RBPrBFNOHQIua0yuvNW/s1600/hit_on_head.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjDWfhmBas_gUKq-SBqewiONopReFgnxfyh4e8w0-64vchI23abTi_jc2E2MrWX1X8y_oUZ_svTxpa4ER_KIYYc-xdeGkLudinZomDiPGjSHZWgzcXJf2M_ylJI5RBPrBFNOHQIua0yuvNW/s320/hit_on_head.png" /></a></td></tr>
<tr style="color: #990000;"><td class="tr-caption" style="text-align: center;"><span style="font-size: xx-small;">Picture source: http://www.chumpysclipart.com/illustration/1199/picture_of_a_soccer_referee_being_hit_on_the_back_of_the_head_with_a_soccer_ball</span></td></tr>
</tbody></table>Now let us look at the structure of a very simple sentence expressed both in active and passive voice.<br />
<blockquote style="color: #990000; font-family: "Trebuchet MS",sans-serif;"><span style="font-size: small;">Active: The installer copied the WAR files to the installation directory.</span><br />
<span style="font-size: small;">Passive: The WAR files were copied to the installation directory.</span></blockquote>This example is a simple example and I wouldn't really prefer one voice over the other. But, consider the following example:<br />
<blockquote style="color: #990000; font-family: "Trebuchet MS",sans-serif;"><span style="font-size: small;">License key definitions are stored in a license key file, which, by default, is named lkad.dat and located in the product installation directory. If you need to modify the list of authorised servers or users, edit the license key file with any text editor.</span></blockquote>Is there any reason why the first sentence needs to be turned into the active voice? Is there any reason why I want to know who is doing the storing action? All I want to know, if I am a license administrator, is where the file is stored (by whoever – I don’t care), what it is named, and how I can edit the license definitions it contains. Passive voice works here, and marvellously.<br />
<br />
Upshot: When I think the doing of an action is important, I write in active voice. When I think it doesn’t matter who or what did or caused the action so long as the action got done, I don’t spend any time changing a passive voice construction to active.<br />
<br />
<div style="color: red;"><b>Writing must be gender neutral</b></div>With all respect to all kinds of genders on this earth, I think that’s a piece of unholy baloney. In English, there is no grammatical gender. But, even though we write in English, there's every likelihood that the text will be translated to at least one language other than English. Many of these non-English languages have grammatical genders. The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on. So, something that is gender neutral in English can very well turn into a gendered phrase in a language like, say, French or Hindi. <br />
<br />
My take is that spending anything more than 5 minutes on rephrasing an otherwise understandable and acceptable-by-usage English sentence into a gender-neutral sentence is nothing but a waste of time.<br />
<br />
<div style="color: red;"><b>Every list should be preceded by an introductory sentence</b></div>The logic is, if I suddenly start a numbered list that has steps to perform a specific task, but do not introduce the list with a stem sentence, readers might be misled, confused, misinformed, etc.<br />
<br />
Now, let’s see the following example:<br />
<blockquote style="color: #990000; font-family: "Trebuchet MS",sans-serif;"><span style="font-size: small;">1. Use one of the following methods to start the Manage Information Catalog wizard:</span><br />
<span style="font-size: small;"></span><br />
<span style="font-size: small;"> * From the Windows desktop, click Start > IBM DB2 > Set-up Tools > Manage Information Catalog wizard.</span><br />
<span style="font-size: small;"> * At a command prompt, enter db2iccwz.</span><br />
<span style="font-size: small;"></span><br />
<span style="font-size: small;">The Manage Information Catalog wizard opens.</span><br />
<span style="font-size: small;"> </span><br />
<span style="font-size: small;">2. Select the Migrate metadata from an existing information catalog option.</span><br />
<span style="font-size: small;"> </span><br />
<span style="font-size: small;">3. Enter the required information on each page of the wizard and click Finish.</span></blockquote>To me, it is apparent this is a procedure for migrating your data from an existing catalog to a new one. To my users, who are undoubtedly smarter than me because they are database administrators [audience, audience], it is very apparent that this is a procedure for migrating data from an old catalog to new; my users just do not need a stem sentence that goes:<br />
<blockquote style="color: #990000; font-family: "Trebuchet MS",sans-serif;"><span style="font-size: small;">To migrate metadata from an existing information catalog:</span></blockquote>The title of the topic would, in any case, always have an indication of what is contained in the topic. The stem sentence adds nothing of value to the content except increasing the word count.<br />
<br />
However, I have also come across procedures where, if a stem sentence were to be absent, important information would be missing. Here is an example:<br />
<blockquote style="color: #990000; font-family: "Trebuchet MS",sans-serif;"><span style="font-size: small;">The following steps are needed only if you overrode the default options when you installed the product.</span></blockquote>The end result – I leave out stem sentences if I think there’s no value add in having them.<br />
<br />
<div style="color: red;"><b>Leave the comparatives and the adverbs alone</b></div>I am in complete agreement. Whether an application is <i>quickly</i> installed, <i>easier</i> to use, and <i>fastest</i> in terms of response time is a conclusion best left to the user to arrive at. Technical writers are supposed to report facts, not hand out value judgements.<br />
<br />
<div style="color: red;"><b>Computers (and computer applications) do not possess human characteristics, so, do not anthropomorphise them</b></div>I agree.<br />
Did I hear someone say, " A piece of software does guide, control, direct my actions. Microsoft Excel lets me create spreadsheets but it does not let me create documents. An umbrella shields me from rain; a car gets me from point A to point B. It’s perfectly okay to anthropomorphise."<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhr94J5zQzkZH5YEkx3DJCswmxeQWV36DRibbJw2jX-DdXBVwFNCCf5gnGVOfQTnbtCwyniQfzDN-LesNJnKh4zQ-nJtdNyICto8yPh9JiS2xzqZN5Jn0tdBKutdRGq1dRFsun1SRGyM2my/s1600/fish_with_umbrella_cartoon.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhr94J5zQzkZH5YEkx3DJCswmxeQWV36DRibbJw2jX-DdXBVwFNCCf5gnGVOfQTnbtCwyniQfzDN-LesNJnKh4zQ-nJtdNyICto8yPh9JiS2xzqZN5Jn0tdBKutdRGq1dRFsun1SRGyM2my/s320/fish_with_umbrella_cartoon.png" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="color: #990000; font-size: xx-small;">Picture source: http://www.wpclipart.com/cartoon/animals/fish/fish_with_umbrella_cartoon.png.html</span></td></tr>
</tbody></table>I disagree with this line of reasoning. When someone says, "The umbrella shields me from rain", that is not anthropomorphism. That’s just someone using a verb correctly because that is indeed what an umbrella does – it shields people from rain. That is an action, not a human characteristic. Now, if someone were to say, "My brave umbrella valiantly tries to shield me from rain but fails", now that, my friend, is anthropomorphism because the umbrella has become possessed of the human characteristic of braveness (and chivalry, perchance).<br />
<br />
Me? I let my software <i>detect</i> conflicts and <i>resolve</i> them but I do not expect it to be <i>remorseful</i> when it crashes my desktop.<br />
<br />
<b> <span style="color: red;">A procedure should not have more than 7 steps</span></b><br />
If anything takes more than 7 steps, says the stricture, break the procedure up into smaller logical pieces. I am guessing this comes from the assumption that readers have short attention spans. I said "guessing" because though I’ve been told there are studies that prove a decrease in comprehension levels after Step 7, I am inclined to believe if someone’s life depended on it, that person would read even <i>War and Peace</i> from cover to cover.<br />
<br />
That said, I do try to keep my procedures as short as possible. But, sometimes, the products we write for do have procedures that cannot be fitted into the 7-step-frame. For example, can the instructions to install a rack-mounted server system really be covered in 7 steps? Really?<br />
<br />
<b><span style="color: red;">Conclusion</span><br />
</b> So, is the cow holy? Well, it depends.<br />
<br />
<div style="text-align: center;"><insert_verb><span style="font-size: x-small;"><span style="font-family: "Trebuchet MS",sans-serif;">[A slightly different version of this blog post was published in STC India's magazine <a href="http://indus.stc-india.org/2010/08/the-myth-of-the-holy-cow/" style="color: blue;"><u>INDUS</u></a>.]</span></span> </insert_verb></div>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com2tag:blogger.com,1999:blog-1520346663771309945.post-78007185731332480072010-09-04T21:44:00.004+05:302010-09-06T12:07:01.177+05:30DITA tools - 4 (Authoring)I've had quite a few of my friends say, "Well, yes, we can do the information typing and we also totally get the semantic tagging concept of DITA but when we get down to actually writing in DITA, it is a bit of a hassle trying to remember all the tag names and where they are allowed. Is there a free WYSISYG editor for all this?"<br />
<br />
In a <a href="http://writing-technical.blogspot.com/2010/02/dita-tools-2.html" style="color: blue;"><u>previous blog post</u></a> I had mentioned one such DITA authoring tool. In this blog post, I will talk about another.<br />
<br />
The Serna XML Editor has a free edition that I've been using the past couple of weeks to do some personal stuff in DITA. For DITA authoring, I really like it and for the following reasons:<br />
<ul><li>It comes bundled with the DITA open toolkit. I don't have to download and install the OT separately.</li>
<li>It also has DocBook (which is next on my personal ToDo list).</li>
<li>Its validators will not let you insert a DITA tag at a place where the tag is not allowed. You will be shown a list of allowable tags, with hovertext for each tag.<br />
<br />
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg94Mw0acqZa-ShdFmH6UZUXTroMt6p2lGYosRvFBig52RDQrLG-AlmWd5DauveYeRxYPV6ciH2LqyRKE8PYeKEg4rondeDPkk5DiIj39MDC4-du042QzwgYV2qysQSQlVdKWBWF7MlkwrV/s1600/serna_insert_element.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg94Mw0acqZa-ShdFmH6UZUXTroMt6p2lGYosRvFBig52RDQrLG-AlmWd5DauveYeRxYPV6ciH2LqyRKE8PYeKEg4rondeDPkk5DiIj39MDC4-du042QzwgYV2qysQSQlVdKWBWF7MlkwrV/s320/serna_insert_element.png" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="color: #990000;">To see a larger image, click on the image</span></td></tr>
</tbody></table></li>
<li>It lets you define the attributes of any element through an element-specific wizard page.<br />
<br />
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi8CZ5WVZs1lrrT7OCXaiw1t0x0rKkjR77ojXGf2hWBSB-8CFpkx2g3TH385AO_-8PN78ZcXweClVvJaxv6Dg2DdWiKmsJUrDsp1xMOmKKuY5Lz_wvOq_fcoZV33KIs94qtKLxegevBgIOC/s1600/serna_element_attributes.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi8CZ5WVZs1lrrT7OCXaiw1t0x0rKkjR77ojXGf2hWBSB-8CFpkx2g3TH385AO_-8PN78ZcXweClVvJaxv6Dg2DdWiKmsJUrDsp1xMOmKKuY5Lz_wvOq_fcoZV33KIs94qtKLxegevBgIOC/s320/serna_element_attributes.png" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="color: #990000;">To see a larger image, click on the image</span></td></tr>
</tbody></table></li>
<li>It lets you drag and drop elements. This is something we (writers) take for granted in our word-processing software but not many free XML editors have this feature.</li>
<li>It is WYSIWYG - not only in terms of DITA tags but also for output previews. To my knowledge, no other free XML editor gives a preview of the output.<br />
<br />
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhHivelnI3Aj8r1fz4mgCdhmYe3PuFcYF6xQN_KTH1isK_BoDgnZzmpLoba8gNXm4D-NFK14TcdErGorxVTKQXo0XSeq46PkqI4DFiDpW2JhTIC_OH0v3HRg3qllR8aQzLg7CmBMPdZBqNv/s1600/serna_output.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhHivelnI3Aj8r1fz4mgCdhmYe3PuFcYF6xQN_KTH1isK_BoDgnZzmpLoba8gNXm4D-NFK14TcdErGorxVTKQXo0XSeq46PkqI4DFiDpW2JhTIC_OH0v3HRg3qllR8aQzLg7CmBMPdZBqNv/s320/serna_output.png" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="color: #990000;">To see a larger image, click on the image</span></td></tr>
</tbody></table></li>
<li>It comes bundled with a transform engine (that's how it has the inbuilt output preview feature). This means you don't need a separate software for running the transforms. You do, however, need the JRE (if you want to publish to XHTML) and FOP (if you want to publish to PDF) - both of which are free to download and easy to install</li>
</ul><br />
The Syntext Serna Free XML Editor can be downloaded from <a href="http://www.syntext.com/products/serna-free/">http://www.syntext.com/products/serna-free/</a>.<br />
<br />
Some of the 'cons' that I've noticed thus far (I am not sure if these are a restriction for the free edition):<br />
<ul><li>The glossary specialisation, though supported, does not result in transformed XHTML files.</li>
<li>Bookmaps, though supported, don't get transformed.</li>
</ul>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com2tag:blogger.com,1999:blog-1520346663771309945.post-64298794920960203832010-05-13T21:02:00.003+05:302010-05-13T21:40:12.061+05:30Writing in DITA - Tips #4 to 10<table width="85%" align="center" border="2"><tbody>
<tr> <td style="text-align: center; color: rgb(153, 0, 0);font-family:courier new;"><span style="font-size:85%;">A verbose version of these tips was published in the Mar-Apr 2010 issue of STC India's newsletter, INDUS, as <a href = "http://indus.stc-india.org/2010/04/dita-writing-tips/"><u>DITA writing tips</u></a>.</span></td></tr>
</tbody></table><p><ol start = 4><li><a href = "#conref"><u>To conref dissimilar elements, wrap the source text in <ph></u></a></li>
<li><a href = "#reltable"><u>To prevent all topics of a <reltable> row from linking back to each other, use the 'linking' attribute of <topicref;</u></a></li>
<li><a href = "#step"><u>To include pretty much anything in a <step>, insert an <info></u></a></li>
<li><a href = "#pre"><u>To preserve the formatting of a copy-pasted text snippet, use <pre></u></a></li>
<li><a href = "#titlealt"><u>To have topics show different titles in different scenarios, use <titlealts></u></a></li>
<li><a href = "#pictures"><u>To caption images, use <fig> as container for <image></u></a></li>
<li><a href = "#short"><u>To have a slightly longer <shortdesc>, put it in an <abstract></u></a></li>
</ol><a name = "conref"></a><br />
<h4>To conref dissimilar elements, wrap the source text in <ph></h4><p>DITA is about content reuse - with a rider. Only like can call like. I cannot, for example, reuse a <step> as an <li> - if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle - say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.</p><a name = "reltable"></a><br />
<h4>To prevent all topics of a relationship table row from linking back to each other, use the 'linking' attribute of the <topicref> element</h4><p>The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. Each row in the table represents a discrete relationship and all files in a row link back to each other. But sometimes I end up with more links than I really want. To prevent that, I qualify the <topicref> tags with either a <font face = "courier">sourceonly</font> attribute or a <font face = "courier">targetonly</font> attribute. When a <topicref> has a <font face = "courier">sourceonly</font> attribute, a link is generated to the target topic <i>only</i> in the source topic; when it's <font face = "courier">targetonly</font>, a link is generated to the source topic <i>only</i> in the target topic.</p><a name = "step"></a><br />
<h4>To include pretty much anything in a <step> tag, use an <info> tag</h4><p>When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.</p><a name = "pre"></a><br />
<h4>To preserve the formatting of a copy-pasted text snippet, use <pre></h4><p>Because DITA is XML, anything enclosed within < > is interpreted as a tag. So how do I include, for example, a code snippet that contais angular brackets? I wrap the text in a <pre> tag, just like I'd have done if I were writing it in HTML.</p><a name = "titlealt"></a><br />
<h4>To have the topic show different titles in different scenarios, use <titlealts></h4><p>I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content. In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what's contained in the <title> tag.</p><a name = "pictures"></a><br />
<h4>To caption images, use <fig> as container for <image></h4><p>The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.</p><a name ="short"></a><br />
<h4>To have a slightly longer <shortdesc>, put it in an <abstract></h4><p>The <shortdesc> element is what I use for writing the "click-through text" for the topic - the text that shows up in search results and in hovertext for links. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I'd still like to retain the shorter short description as the "pull text", but what if I want to add another two sentences and want to have them all in that section itself - the first section on a page - instead of carrying the extra sentences over to the body of the topic (where they'll probably have to reside <i>after</i> a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag</p>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-52044877615947188432010-05-09T20:59:00.003+05:302010-05-13T21:19:17.780+05:30DITA 1.2 - New <task> elementsThe DITA language specification v1.2 introduces two new task elements: <span style="color: #990000;"><steps-informal></span> and <span style="color: #990000;"><stepsection></span>. <br />
The <span style="color: #990000;"><steps-informal></span> element is for describing procedural information that is otherwise not normally described as a step. The <span style="color: #990000;"><stepsection></span> is for giving explanatory information before a step. It is contained within the <steps> element and can be placed betweeen two <step> elements; the output of the content of a <stepsection> will not contain a bullet or a number.<br />
<h4>When should I use the <steps-informal> and <stepsection> elements</h4><span style="color: #990000;"><steps-informal></span>: The v1.2 language specifications haven't yet included an example of the <steps-informal> element so I am still a bit unclear about how and when to use it.<br />
<span style="color: #990000;"><stepsection></span>: If I am using DITA v1.1 and need to give some info before a step, the only way I could do that was insert an <info> in the <i>previous</i> step. With <stepsection>, this problem is resolved. Here's an example (taken from the v1.2 lang specs doc):<br />
<blockquote><pre><steps>
<step><cmd>Get out a bowl</cmd></step>
<stepsection>The next two steps are very important!</stepsection>
<step><cmd>Put on safety gloves</cmd></step>
<step><cmd>Put on goggles</cmd></step>
<step><cmd>Pour milk and cereal into the bowl</cmd></step>
</steps>
</pre></blockquote><h4>Related information</h4>With v1.2, a <step> can have an <note> <i>before</i> the <cmd>.<br />
<p> </p>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-67528423286861658122010-05-07T22:00:00.007+05:302010-05-13T21:19:17.782+05:30DITA 1.2 - New <topic> elementsThe DITA language specification v1.2 introduces two new topic elements:<span style="color: #990000;"> <bodydiv></span> and <span style="color: #990000;"><sectiondiv></span>. <br />
The <span style="color: #990000;"><bodydiv></span> element is intended to be used as a grouping element for containing logical blocks of info that otherwise do not need either a title or a separate topic. It can be placed only within a <body> or within another <bodydiv>.<br />
The <span style="color: #990000;"><sectiondiv></span> element is similar to the <bodydiv> element except that it has more container elements - it can be placed within a <section>, <sectiondiv>, and a bunch of other tags depending upon the topic type.<br />
<h4>Why and when should I use <bodydiv> and <sectiondiv></h4>If I want to reuse a whole group of info somewhere else, these two tags are handy. Not that such reuse couldn't have been done otherwise, but then, these tags can, for example, contain several <p> elements, some lists, some images...it's almost like being able to reuse an <i>information chunk</i> instead of individual tags. Without being actual formal topics, these tags behave like topics.<br />
<h4>Related information</h4>The <concept> topic type also has a new element in v1.2 that's similar to <bodydiv> and <sectiondiv>. It's called <conbodydiv>.<br />
<h4>History of <topic> elements</h4>Here's a list of the various topic elements from v 1.0 to 1.2:<br />
<br />
<table align="center" border="1"><tbody>
<tr> <td width="33%"><b>DITA 1.0</b></td><td width="33%"><b>DITA 1.1</b></td><td width="33%"><b>DITA 1.2</b></td> </tr>
<tr> <td width="33%">dita</td><td width="33%">-</td><td width="33%">-</td> </tr>
<tr> <td width="33%">topic</td><td width="33%">topic</td><td width="33%">topic</td> </tr>
<tr> <td width="33%">title</td><td width="33%">title</td><td width="33%">title</td> </tr>
<tr> <td width="33%">titlealts</td><td width="33%">titlealts</td><td width="33%">titlealts</td> </tr>
<tr> <td width="33%">navtitle</td><td width="33%">navtitle</td><td width="33%">navtitle</td> </tr>
<tr> <td width="33%">searchtitle</td><td width="33%">searchtitle</td><td width="33%">searchtitle</td> </tr>
<tr> <td width="33%">-</td><td width="33%">abstract</td><td width="33%">abstract</td> </tr>
<tr> <td width="33%">shortdesc</td><td width="33%">shortdesc</td><td width="33%">shortdesc</td> </tr>
<tr> <td width="33%">body</td><td width="33%">body</td><td width="33%">body</td> </tr>
<tr> <td width="33%">-</td><td width="33%">-</td><td width="33%">bodydiv</td> </tr>
<tr> <td width="33%">section</td><td width="33%">section</td><td width="33%">section</td> </tr>
<tr> <td width="33%">-</td><td width="33%">-</td><td width="33%">sectiondiv</td> </tr>
<tr> <td width="33%">example</td><td width="33%">example</td><td width="33%">example</td> </tr>
<tr> <td width="33%">related-links</td><td width="33%">related-links</td><td width="33%">related-links</td> </tr>
</tbody></table>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-34037955487286870592010-04-09T19:34:00.005+05:302010-05-09T20:38:19.598+05:30Writing in DITA - Tip # 3While authoring, I often need to refer to that specific directory, that particular URL, this specific file which resides in this specific directory. As the software development cycle progresses, names change (and how). By the time people are ready for bit freeze, I am out of my mind worrying if all the specific references I put in your doc are updated (specific references are more "consumable" by a user). But if I've had the time to plan, I'd have probably envisaged such a scenario and prepared myself. How? I give here two alternatives (there could be more but I don't know of them yet). And, because I am making a case for Alternative 2, I'll shoot down each of the examples that I give for Alternative 1.<br />
<h4>Alternative 1</h4>Do not use specifics. Talk in generic terms. Examples:<br />
<br />
<ul><li>From the Sun website, download the latest version of the Java Development Toolkit.<br />
Problem: For all you know, Sun might be acquired by Moon, and the JDK be renamed to Lunar NetBeams.<br />
</li>
<li>In the installation directory of the software application, look for a file with a name that has a suffix that correspond to the product acronym as listed in the Offical Acronyms page of the software application.<br />
problem: Which software application? You said Package A was prerequisite for Package B so I downloaded both from your website and installed them and they seem to be installed in the same directory - the directory name is the name of your company. Which subdirectory of the installation directory? There are no files in the main directory. Where is the Acronyms page? The first three hits in Google lead me to pages not maintained by your company.<br />
</li>
</ul><h4>Alternative 2</h4>Use the conref facility provided by DITA.<br />
DITA is about content reuse. We might as well rephrase that to say, "DITA is about reducing maintenance overheads". (<aside>The first sentence talks about a feature. The second about a benefit. Users look for benefits (what's in it for me), not features. Am a bit puzzled why so many techcomm people keep using the first sentence without, ah, repurposing it for the target audience.</aside>)<br />
<br />
This is how I do it: I maintain a separate file called in which I have a bunch of text that I think are of a variable nature. Each chunk of reusable text is wrapped in a <ph> element and given an ID. Like this:<br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjGTpqC9IfZ6t5HjxzAJzpXFjmQvU1s0HBKnkHCW2qwx7TRBrdLIlaGAO327kLqWWzNI4F07sdVLxva_3uxrSUrP_o3Nqup28TVun6ngVyqB5WNXdYrHoToJLYhQdAU5j4VeB0bl3Q4RG9S/s1600/DITA_conref_1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="73" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjGTpqC9IfZ6t5HjxzAJzpXFjmQvU1s0HBKnkHCW2qwx7TRBrdLIlaGAO327kLqWWzNI4F07sdVLxva_3uxrSUrP_o3Nqup28TVun6ngVyqB5WNXdYrHoToJLYhQdAU5j4VeB0bl3Q4RG9S/s640/DITA_conref_1.png" width="640" /></a></div><br />
Then, in the main files, I just conref these <ph> chunks. The text comes out looking like this:<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi4jWS4mGjhKHMBjftVwAwNzeb5Se3usYIaK83OEzfMB2CQXZ0ZGNMSLnrBJx3xQ0LzV4TwzxtpZGhYDAHHgLfxzLZODmznxvIQ43Tv33GI4_9UuLAnnyHlcu58IJWM8F7Gu5uKHGmLA_7q/s1600/DITA_conref_2.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="108" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi4jWS4mGjhKHMBjftVwAwNzeb5Se3usYIaK83OEzfMB2CQXZ0ZGNMSLnrBJx3xQ0LzV4TwzxtpZGhYDAHHgLfxzLZODmznxvIQ43Tv33GI4_9UuLAnnyHlcu58IJWM8F7Gu5uKHGmLA_7q/s640/DITA_conref_2.png" width="640" /></a></div>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-88357530734501531332010-03-24T00:30:00.002+05:302010-03-24T01:11:02.769+05:30DITA tools - 3 (Transforming)To transform dita files to a publishable output, such as XHTML or PDF, we need to run ANT builds, and we do it through the DOS command line. Another option is to use a GUI. I find the WinAntEchidna GUI, developed by HyperText, to be very handy.<br />
<br />
The first time that you use WinAntEchidna, it asks you for the installation directory of the DITA OT (this, like all parameters, can be changed any time). Thereafter, every time you run WinAntEchidna, all you need to do is specify your ditamap file, your output folder, and your output type.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhqM-uY-MIng0dPUAJvQQIGxi9MNfVKjxtUFYmoMhadZAQT_sSbvqTocoXzgxEdazzHxO6g2rcqVP8iM_mckHn05EJqpB_p-A2MZYzL1rlZY0DevHlsdSgpvA5KsVu8kdfsOtcc1GbWYtCr/s1600-h/WinAntEchidna.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhqM-uY-MIng0dPUAJvQQIGxi9MNfVKjxtUFYmoMhadZAQT_sSbvqTocoXzgxEdazzHxO6g2rcqVP8iM_mckHn05EJqpB_p-A2MZYzL1rlZY0DevHlsdSgpvA5KsVu8kdfsOtcc1GbWYtCr/s320/WinAntEchidna.png" /></a></div><br />
WinAntEchidna can be downloaded from <a href="http://sourceforge.net/projects/winant-echidna/"><u>http://sourceforge.net/projects/winant-echidna/</u></a>.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-40822554900094969772010-03-22T20:33:00.008+05:302011-02-11T23:07:08.545+05:30Quick and rude guide to DITA OT installationThe install guide that comes with the DITA OT package is good (really, no sarcasm) but it sometimes assumes I am more of a techie than I really am. Last week, I changed my computer. It was while setting up my DITA environment that I remembered again that if I just follow these instructions to the T (see picture), I am more than likely to stumble.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhxqnVVmz-GGkTMFoM1YoqG71moy1LEd4GuEgDFalcQ_MijCHS-xOsYObW8PtdRJyvqOUHg8IxePlHyINX2Pi11k6u7GbRAR4RIofSV1CNXc-PIoSWllQcLbTgt8NFdQeUCppXp1ak57Sj6/s1600-h/DITA_OT_1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhxqnVVmz-GGkTMFoM1YoqG71moy1LEd4GuEgDFalcQ_MijCHS-xOsYObW8PtdRJyvqOUHg8IxePlHyINX2Pi11k6u7GbRAR4RIofSV1CNXc-PIoSWllQcLbTgt8NFdQeUCppXp1ak57Sj6/s320/DITA_OT_1.png" /></a></div>So, I am writing up this blog post as a note to (i) myself, should I need to do this all over again (ii) everyone of you who wants to set up a DITA environment with minimal fuss. (<span style="color: blue;"><aside></span>I know; "minimal" is subjective.<span style="color: blue;"></aside></span>)<br />
<br />
I use a Windows machine; these instructions are for a Windows setup (64-bit).<br />
<ol><li>Download JDK. The latest version is JDK 6 Update 18 and can be downloaded from <span style="color: #990000; font-family: "Courier New",Courier,monospace;">http://java.sun.com/javase/downloads/index.jsp</span>. The file I downloaded is called <span style="color: #990000; font-family: "Courier New",Courier,monospace;">jdk-6u18-windows-i586.exe</span>.</li>
<li>Install JDK to a directory of your choice. To do so, double-click the <span style="color: #990000; font-family: "Courier New",Courier,monospace;">jdk-6u18-windows-i586.exe</span> file and follow the onscreen instructions. Stick to the default options. For the remaining part of this procedure, let's assume the JDK installation directory is <span style="color: #990000; font-family: "Courier New",Courier,monospace;">C:\Program Files (x86)\Java\jdk1.6.0_18</span>.</li>
<li>Download HTML Help Workshop. The file is called <span style="color: #990000; font-family: "Courier New",Courier,monospace;">htmlhelp.exe</span> and can be downloaded from <span style="color: #990000; font-family: "Courier New",Courier,monospace;">http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en</span>.</li>
<li>Install HTML Help Workshop. To do so, double-click the <span style="color: #990000; font-family: "Courier New",Courier,monospace;">htmlhelp.exe</span> file and follow the onscreen instructions. Stick to the default options.</li>
<li>Download the full DITA OT package. The latest stable version is 1.5 and can be downloaded from <span style="color: #990000; font-family: "Courier New",Courier,monospace;">http://sourceforge.net/projects/dita-ot</span>. The file I downloaded is called <span style="color: #990000; font-family: "Courier New",Courier,monospace;">DITA-OT1.5.1_full_easy_install_bin.zip</span>.</li>
<li>Extract the contents of the DITA OT package to any directory of your choice. For the remaining part of this proceudre, let's assume this directory to be <span style="color: #990000; font-family: "Courier New",Courier,monospace;">C:\Work_Area\DITA</span>.</li>
<li>In the <span style="color: #cc0000; font-family: "Courier New",Courier,monospace;">C:\Work_Area\DITA</span> directory, look for a file called <span style="color: #990000; font-family: "Courier New",Courier,monospace;">startcmd.bat</span>, and double-click it.</li>
<li>In the command line window that opens, set the JAVA_HOME environment variable by running the following command: <span style="color: #990000; font-family: "Courier New",Courier,monospace;">set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.6.0_18</span></li>
<li>In the same command line window, test your DITA OT installation by running the following command (which is an ANT command for transforming DITA files): <span style="color: #990000; font-family: "Courier New",Courier,monospace;">ant samples.web -f build_demo.xml</span> Wait for the command to get over.</li>
<li>Return to Windows Explorer and, in the <span style="color: #990000; font-family: "Courier New",Courier,monospace;">C:\Work_Area\DITA</span> directory, look for a folder called <span style="color: #990000; font-family: "Courier New",Courier,monospace;">out</span>. This folder was created as a result of the previous step and contains the transformed files. If you cannot find this folder, something went wrong with the installation :-(</li>
</ol>Notes for subsequent transforms: Set the Java environment variables every time you run an ANT build, and do it from the directory where the ANT build is being run.<br />
<br />
<b>Related posts</b><br />
Now that DITA OT is installed, you might want to get yourself an authoring tool? See this blogpost: <a href="http://writing-technical.blogspot.com/2010/02/dita-tools-2.html"><u>DITA authoring tool</u></a>. <br />
Next, you might want to run your transforms, no, not through the command line, but through a GUI? My next blog post is about such a transform tool: <a href="http://writing-technical.blogspot.com/2010/03/dita-tools-3.html"><u>DITA tools - 3 (Publishing)</u></a>.<br />
<br />
<b>Post script</b><br />
The procedure I wrote contains several inline links, and references to specific software versions and local directories. As any writer knows, these are maintenance headaches. Whether docs can (or, should) really have such specific info, and, if yes, how to include such info with minimal maintenance overheads is explored in this blog post: <a href="http://writing-technical.blogspot.com/2010/04/writing-in-dita-tip-3.html"><u>Writing in DITA - Tip #3</u></a>.Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com8tag:blogger.com,1999:blog-1520346663771309945.post-10488858624023606972010-03-18T23:06:00.003+05:302010-03-18T23:10:50.241+05:30Writing in DITA - Tip #1 alternate solutionThe problem statement is this: <a href="http://writing-technical.blogspot.com/2010/03/writing-in-dita-tip-1.html"><u>Cannot put link text inside <xref></u></a>.<br />
<br />
An alternate solution is here:<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiSgxdYWKAZAXgr6r5rqMY71ogljLrMYQQtIWPfgjRikHD4VhCuXMVJCwnWaAR7Uoliea1PVD-MxexE4QxnE8OiArkR80ml-2V-kZNozfLUKWJY4G6jcyz2uqlLkH7MtdUJDHYPjAskKpJP/s1600-h/arbortext_xref_99.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="101" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiSgxdYWKAZAXgr6r5rqMY71ogljLrMYQQtIWPfgjRikHD4VhCuXMVJCwnWaAR7Uoliea1PVD-MxexE4QxnE8OiArkR80ml-2V-kZNozfLUKWJY4G6jcyz2uqlLkH7MtdUJDHYPjAskKpJP/s400/arbortext_xref_99.gif" width="400" /></a></div><div style="text-align: center;"><span style="font-size: x-small;">Cartoon created with http://www.makebeliefscomix.com.</span></div>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-83433871474365014292010-03-17T21:42:00.004+05:302010-03-17T22:26:56.391+05:30Writing in DITA - Tip #2You are writing a procedure. You are, therefore, using <span style="color: #990000;"><steps></span> for your list of actions that your reader needs to follow to complete the task. You have in mind something like this:<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiDrO_w9zfCJCeK-P7myZNHZ8_tIyjoT-iUf2TVcIoD1v2NrU9NIZXy1S3to0WKCzwrqqqbqHyMqLo-MUSHYHGjepmVe1Hz_iQ_ccyYgZyWrYIoAsunwwNYHqaqrZCV2OEt2e5zquMmC8bC/s1600-h/li_p_1.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiDrO_w9zfCJCeK-P7myZNHZ8_tIyjoT-iUf2TVcIoD1v2NrU9NIZXy1S3to0WKCzwrqqqbqHyMqLo-MUSHYHGjepmVe1Hz_iQ_ccyYgZyWrYIoAsunwwNYHqaqrZCV2OEt2e5zquMmC8bC/s320/li_p_1.gif" vt="true" /></a></div>Because DITA tags are semantic, you want to enclose <span style="background-color: #ead1dc; color: #990000; font-family: "Courier New",Courier,monospace;">db2iauto -on <instance name><span style="background-color: white;"> </span></span>within a <span style="color: #990000;"><codeblock></span> tag. But you hit a roadblock. You cannot include a <span style="color: #990000;"><codeblock></span> tag within a <span style="color: #990000;"><step></span><span style="color: black;"> tag</span>, says the DITA language specification.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi6FuGXaLpRVn0RdTyTY6abKiR0sb_GLyTA0uKH0Op6J_0QZ8KZUHZIsSKwtGRRR478Ti006T-XHuv-51XykRGUK6aVkt62d5LBimA42Jfu31quSln2Oh_JAAer0rvSlmZgn_gj1wkpdf2k/s1600-h/li_p_2.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi6FuGXaLpRVn0RdTyTY6abKiR0sb_GLyTA0uKH0Op6J_0QZ8KZUHZIsSKwtGRRR478Ti006T-XHuv-51XykRGUK6aVkt62d5LBimA42Jfu31quSln2Oh_JAAer0rvSlmZgn_gj1wkpdf2k/s320/li_p_2.gif" vt="true" /></a></div>What do you do now?<br />
Insert an <span style="color: #990000;"><info></span> tag after the mandatory <span style="color: #990000;"><cmd></span> tag in the <span style="color: #990000;"><step></span> tag. Then, insert <span style="color: #990000;"><codeblock></span> within the <span style="color: #990000;"><info></span> tag.<br />
The <span style="color: #990000;"><info></span> tag is pretty useful - it can contain paragraphs, lists, notes, images, ...<br />
<p> </p><p> </p>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0tag:blogger.com,1999:blog-1520346663771309945.post-29607423140068739802010-03-16T16:38:00.011+05:302010-04-05T20:41:33.419+05:30Writing in DITA - Tip #1<div class="separator" style="clear: both; text-align: center;"></div><h3>Problem statement</h3>Theoretically, the <span style="color: #990000;"><xref></span> tag can contain plain text. It must therefore be possible to write something like:<br />
<blockquote><table align="center"><tbody>
<tr><td><br />
<div style="background-color: #ead1dc; font-family: "Courier New",Courier,monospace;"><span style="font-size: small;"><xref format="html"</span></div><div style="font-family: "Courier New",Courier,monospace;"><span style="font-size: small;"><span style="background-color: #ead1dc;">href="http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/topic/com.ibm.swg.im.cognos.ug_fm.8.4.0.doc/ug_fm_id21834Troubleshooting.html#Troubleshooting" scope="external"></span>Troubleshooting guide<span style="background-color: #ead1dc;"></xref></span> </span></div></td> </tr>
</tbody></table></blockquote>The authoring tool we use at work (Arbortext Editor) very decidedly does not think so.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiA_KUtIrLwO3kMgzKpPfvRj6mgcJZ1RP9lWEDKBCq79fazfDuFY52Dsq2P-x2wf2OonpB0mu_Zhbs09AFuHQ7qli7oBSlI__f1TMRVwDIO5ur0rhmw16iXPgKsj99-GgZLS8cZfjn6pcoZ/s1600-h/arbortext_xref_1.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="115" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiA_KUtIrLwO3kMgzKpPfvRj6mgcJZ1RP9lWEDKBCq79fazfDuFY52Dsq2P-x2wf2OonpB0mu_Zhbs09AFuHQ7qli7oBSlI__f1TMRVwDIO5ur0rhmw16iXPgKsj99-GgZLS8cZfjn6pcoZ/s320/arbortext_xref_1.gif" width="320" /></a></div><div class="separator" style="clear: both; text-align: center;"></div>So, the resulting output looks, er, ugly.<br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEje54Qci_VWRMbxrSiI2FK9IiSjc2JkMWHETBstngQ5LH_bfNaIeNc4v7f3LcodoKKxWqWlYR7vz6i_yg73dHjO7AhAdw5TtcexH18FSUIVPNEcYr34GhR-GF0kiwnIE28LLkVf4_hqKb2E/s1600-h/arbortext_xref_3.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="43" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEje54Qci_VWRMbxrSiI2FK9IiSjc2JkMWHETBstngQ5LH_bfNaIeNc4v7f3LcodoKKxWqWlYR7vz6i_yg73dHjO7AhAdw5TtcexH18FSUIVPNEcYr34GhR-GF0kiwnIE28LLkVf4_hqKb2E/s320/arbortext_xref_3.gif" width="320" /></a></div><h3>Workaround</h3><b>Step 1</b>: Insert a <span style="color: #990000;"><desc></span> tag inside the <span style="color: #990000;"><xref></span> tag, type something within the <span style="color: #990000;"><desc></span> tag (it shows up as hovertext in transformed output), and then type something just outside the <span style="color: #990000;"><desc></span> tag but still within the <span style="color: #990000;"><xref></span> tag. Like this:<br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjVMu7dlhsBVSbF_m8d8qz1274R1g10AfVbgY4Y8V_vz2iwsanohk_Fm4hdhwyCxe3vIJQIPETrDhZzTFq4fPOA3MUZLmpL8i2D0aQAgi0WfezJx7fklwcI9UKDzpH9oCrdAI79Cu8gdyZA/s1600-h/arbortext_xref_2.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="54" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjVMu7dlhsBVSbF_m8d8qz1274R1g10AfVbgY4Y8V_vz2iwsanohk_Fm4hdhwyCxe3vIJQIPETrDhZzTFq4fPOA3MUZLmpL8i2D0aQAgi0WfezJx7fklwcI9UKDzpH9oCrdAI79Cu8gdyZA/s320/arbortext_xref_2.gif" width="320" /></a></div><b>Step 2</b> (optional): Delete the <span style="color: #990000;"><desc></span> tag.<br />
<b>Step result</b><br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjmjAZ_AHc8a1ixyl6zGZYaJa5F8yCCBgcjQlXc0Hcww0sFqAeMDgCqLb02QwLLyn5ufMpERjajYoHTpSNdFutzuCXHmSV8oA-aTyouv2cjcnEvn4n6P7j6a03v7wNfaxjH5KO2kr0V_rpH/s1600-h/arbortext_xref_4.gif" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="21" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjmjAZ_AHc8a1ixyl6zGZYaJa5F8yCCBgcjQlXc0Hcww0sFqAeMDgCqLb02QwLLyn5ufMpERjajYoHTpSNdFutzuCXHmSV8oA-aTyouv2cjcnEvn4n6P7j6a03v7wNfaxjH5KO2kr0V_rpH/s320/arbortext_xref_4.gif" width="320" /></a></div><h3>Musings</h3>I am fairly sure the problem is not a DITA bug but an Arbortext Editor bug. Anyone seen anything similar?<br />
<br />
<h4>Post script,2 days after original post</h4>See an alternate solution <a href="http://writing-technical.blogspot.com/2010/03/writing-in-dita-tip-1-alternate.html"><u>here</u></a>.<br />
<br />
<h4>Another post script, 20 days after the original post</h4>The Arbortext people found this blog post and offered to help but by that time I had already found a solution. I am impressed by their follow-up - they are really trying to keep track of user pain points and minimising the attendant frustration. Thank you Arbortext (and Liz Fraley).<br />
I'm still not sure, though, if it's not an Arbortext bug. The error message box is captioned "Arbortext..." and it has a bug number. The problem was I couldn't find a list of error messages (and possible resolutions) in the Arbortext help. Per my understanding, the problem seems to be - text selected within an xref tag cannot be overwritten; it can be removed only if <i>it is not selected</i> AND some other text is typed in AND the "generate referenced text" button clicked again. Maybe it's not a bug. But as far as I know, a standard method of deleting text is by overwriting it. Maybe an error message section in the help docs would help?Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com6tag:blogger.com,1999:blog-1520346663771309945.post-33874827686631369452010-03-04T20:47:00.010+05:302010-03-06T20:17:41.108+05:30DITA and DITA-OTMy attempt to answer a question that keeps coming my way at regular intervals: isn't DITA-OT the same as DITA?<br />
Short answer: No. Longer answer: Read on.<br />
<table border-color="#000066" border="2" style="font-family: "Trebuchet MS",sans-serif;"><tbody align="top">
<tr align="top" bgcolor="#cccccc"> <td></td> <td align="top" style="color: #990000;">DITA</td> <td align="top" style="color: #990000;">DITA-OT</td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">What is the full form</td> <td align="top">Darwin Information Type Architecture</td> <td align="top">DITA Open Toolkit</td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">What is it</td> <td align="top">A standard. An XML-based architecture for authoring, producing, and delivering technical information</td> <td align="top">A set of Java-based, open-source tools for processing DITA files</td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">What is the latest stable version</td> <td align="top">1.1</td> <td align="top">1.5</td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">Where is it</td><td align="top" style="color: blue;"><a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita"><u>OASIS DITA Technical Committee</u></a></td> <td align="top" style="color: blue;"><a href="http://sourceforge.net/projects/dita-ot/"><u>Sourceforge</u></a></td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">Who owns it</td> <td align="top">OASIS DITA Technical Committee</td> <td align="top">Err, nobody. It's an open-source implementation licenced under CPL 1.0 and Apache Licence v2.0</td> </tr>
<tr align="top"> <td align="top" bgcolor="#cccccc" style="color: #990000;">When's the next update</td> <td align="top">1.2, under development since 2007 (<a href="http://wiki.oasis-open.org/dita/FrontPage" style="color: blue;"><u>track what's happening</u></a>)</td> <td align="top">1.5.1, planned as a point release for DITA 1.2 and to coincide with the DITA 1.2 release</td> </tr>
</tbody></table><p> </p>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com2tag:blogger.com,1999:blog-1520346663771309945.post-16350145822216969832010-03-01T23:46:00.002+05:302010-03-23T13:24:14.633+05:30Help and its Usability<table width="85%" align="center" border="2"><tbody>
<tr> <td style="text-align: center; color: rgb(153, 0, 0);font-family:courier new;"><span style="font-size:85%;">A verbose version of this wishlist was published in the <a href = "http://indus.stc-india.org/2010/02/jan-feb-2010-newsletter/" target = "_blank"><u>Jan-Feb 2010</u></a> issue of STC India's newsletter INDUS.</span></td></tr>
</tbody></table><br />
What if my Help was not at all like the Help as we usually see it?<br />
<br />
What if every menu option had a tiny Help button with a hovertext that tells me the consequences of a click-through.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj93DYYQALPtsu3cKt0uucb6SrsGK6mXreMtSn31-LKsbbVbIfvRXdtj0r2OY88NPvFqhhcVX7bjAImFWOuCltE_jugl47SvSN-UUL7Nho1Fv9nGXyqZQNHiq6b9KPBg8zCWU8nhstObPAO/s1600-h/help_hover.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj93DYYQALPtsu3cKt0uucb6SrsGK6mXreMtSn31-LKsbbVbIfvRXdtj0r2OY88NPvFqhhcVX7bjAImFWOuCltE_jugl47SvSN-UUL7Nho1Fv9nGXyqZQNHiq6b9KPBg8zCWU8nhstObPAO/s320/help_hover.png" /></a></div><br />
What if there was no ToC? What if, instead of a tree of topics, I am shown only one topic? The topic that I reached by clicking the tiny Help button on the options on the menu bar?<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjF94FBZrMRhdC_g7N_EoWPgEh1woPvqbBs-SxmDK3eLamV-58D7dyni6NwOZpLe9zOVyghHJQ3joA5oQyEWZvSVtgtjt-Gi_vS7-WIVTQf1_bfOiZoK8WwRITm-VdwWiS6moBbY2e-6TGQ/s1600-h/help_singletopic.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjF94FBZrMRhdC_g7N_EoWPgEh1woPvqbBs-SxmDK3eLamV-58D7dyni6NwOZpLe9zOVyghHJQ3joA5oQyEWZvSVtgtjt-Gi_vS7-WIVTQf1_bfOiZoK8WwRITm-VdwWiS6moBbY2e-6TGQ/s320/help_singletopic.png" /></a></div><br />
What if every Help topic helps me orient myself with a You-Are-Here clickable flow-diagram.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjt787guYSX3X8T8PrRpo-OwfyTZ5UhurIX34WM1l0KIgr-HBVby5sEitMiX-W5h5ze_0dSkMC8NRaQrBQO5uq-HrE_SIG-GErfLNzWr5VBGnWqeP9kswFp0j0-kkK0WGGy2i30X_rYfGwR/s1600-h/help_roadmap.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjt787guYSX3X8T8PrRpo-OwfyTZ5UhurIX34WM1l0KIgr-HBVby5sEitMiX-W5h5ze_0dSkMC8NRaQrBQO5uq-HrE_SIG-GErfLNzWr5VBGnWqeP9kswFp0j0-kkK0WGGy2i30X_rYfGwR/s320/help_roadmap.png" /></a></div><br />
What if all UI fields had examples?<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjWlWSwFAhnTLjpYyLsdm8zP3ZfDx831W-npeelTYR72KPvauFkJTNC6lrszbRWMvrhV3BfPhSNECK5lPP3ND4oCjYbSexzkfoifPEiI8lqBjJA72NxS80AJmwbyy8kIRCueYRSLGQAQXaf/s1600-h/help_example.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjWlWSwFAhnTLjpYyLsdm8zP3ZfDx831W-npeelTYR72KPvauFkJTNC6lrszbRWMvrhV3BfPhSNECK5lPP3ND4oCjYbSexzkfoifPEiI8lqBjJA72NxS80AJmwbyy8kIRCueYRSLGQAQXaf/s320/help_example.png" /></a></div><br />
What if the Help button on a UI field opened for me a page that shows the results of a predefined search – a search based on the UI screen I was at (and related to the task I was doing) when I clicked the question mark?<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjhdQHHKexFOyxD1PC-z_SMMltbn5fSDEy2ywkiEbymdUF73JB2LP-15biDLSfXEiQ7L7YbzDlf5y7ol1c6825XCEitG_PuCjCk83Cqmb0DrhP7u45-bhnf6bNQSI35Z0joO5shXieAAr8s/s1600-h/help_customsearch.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjhdQHHKexFOyxD1PC-z_SMMltbn5fSDEy2ywkiEbymdUF73JB2LP-15biDLSfXEiQ7L7YbzDlf5y7ol1c6825XCEitG_PuCjCk83Cqmb0DrhP7u45-bhnf6bNQSI35Z0joO5shXieAAr8s/s320/help_customsearch.png" /></a></div><br />
What if the UI had embedded cheat sheets that guide me along.<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiXPj0t9FQcsEYMmUWdiMEDHeAjjhTIyIosTruAhWhrRwRGmdQF4EFdWtQWWllmWZz_Zp0k9KSnmW6o67TfLaFgZopMcDr0MF_pljkymu9qH4iqrKrok7BbAnlwQ0DniNBlN6Q3rUCq8-ZD/s1600-h/help_cheatsheet.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiXPj0t9FQcsEYMmUWdiMEDHeAjjhTIyIosTruAhWhrRwRGmdQF4EFdWtQWWllmWZz_Zp0k9KSnmW6o67TfLaFgZopMcDr0MF_pljkymu9qH4iqrKrok7BbAnlwQ0DniNBlN6Q3rUCq8-ZD/s320/help_cheatsheet.png" /></a></div><br />
What if I had On-the-spot troubleshooting where an error message, instead of telling me what went wrong, pops up a wizard with which I can do that which should have been done in the first instance?<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj_SX0YFPLSr_1e0Oqf3EiSPPn3znND0J73YihEuq6SLVwAIcm5YMnTgJcytFQhCsY9M5IdVuEAVTM-lTBH0J5DZcNDtvVCZMlnQze_S934pqUl7KmrRCbUgXcNXI_Og8GDfbynn8414R-8/s1600-h/help_troubleshoot.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj_SX0YFPLSr_1e0Oqf3EiSPPn3znND0J73YihEuq6SLVwAIcm5YMnTgJcytFQhCsY9M5IdVuEAVTM-lTBH0J5DZcNDtvVCZMlnQze_S934pqUl7KmrRCbUgXcNXI_Og8GDfbynn8414R-8/s320/help_troubleshoot.png" /></a></div><br />
What if wishes were horses? Why, I'd gallop along on my tasks with nary a roadblock in sight.<br />
<p> </p>Anindita Basuhttp://www.blogger.com/profile/03352360406165885914noreply@blogger.com0