DITA quick and rude guides
- Quick and rude guide to DITA OT installation: Because the DITA OT install guide assumes I know stuff that I don't know.
- Quick and rude guide to DITA - Part 1 of 3: DITA is about chunks and tags. And, topic types.
- Quick and rude guide to DITA - Part 2 of 3: Writing your first DITA topic.
- Intermission: Break time.
- Quick and rude guide to DITA - Part 3 of 3: You need not really bother yourself with this part unless you're eager to see how your DITA files look in HTML.
- DITA and DITA-OT: Aren't they the same?
DITA versions
- DITA 1.2 - New <task> elements: <steps-informal> and <stepsection>.
- DITA 1.2 - New <topic> elements: <bodydiv> and <sectiondiv>.
DITA tools
- DITA tools - 1 (Planning): IBM Information Architecture Workbench is an Eclipse-based freeware that I find marvellously handy for organising my thoughts and then committing those thoughts to DITA file types and maps.
- Dita tools - 2 (Authoring): I am very comfortable using Notepad to write in DITA. But there are times when I forget if a particular DITA tag can be used at a particular place. That's when XMLMind is handy.
- DITA tools - 3 (Transforming): Running the ANT builds through a GUI.
- DITA tools - 4 (Authoring): A free WYSIWYG editor with an output preview and built-in transform engine.
Writing in DITA
- Writing in DITA - Tip #1: Inserting a link text within an xref tag. An alternate solution is at Writing in DITA - Tip #1 alternate solution
- Writing in DITA - Tip #2: Inserting a code snippet within a step tag.
- Writing in DITA - Tip #3: Reduce maintenance, use conref.
- Writing in DITA - Tips #4 to 10: A bunch of 'em.
- My book on DITA: Writing in progress.
Usability
- Help and its Usability: Wishlist for the here-and-now times.
- When the ToC spins out of control: ...the install guide has all info but it's difficult to figure out what is located where...
- Task flow - Analysed?: An example from a cerdit card company.
- User scenarios, anybody?: An example from the kitchen.
- User is king: An example from a bank's FAQ.
- Comparing Blogger.com and WordPress.com: ...
- If it’s not easy to use, it’s not used: If something is not easy to use, is anyone going to use it?
Writing
- Technical writing lessons from films: Or, how to deliver quality documentation.
- Where is the User in the Design: Is my content creation and delivery helping the reader?
- Where is the User in the Guide: Does my content answer user questions?
- Of Currency Notes and Information: Easter eggs in documentation
- The Story of a User Manual: In the beginning, there was the Word.
- How to write badly: Pointers that help you be a bad technical writer.
- When the ToC spins out of control: ...the install guide has all info but it's difficult to figure out what is located where...
- Bad docs rarely mean bad sales: Technical writing is a cost activity, not a revenue or a profit activity.
- Do I speak your language: Else, you won't understand me.
- The engaged reader: Almost every bullet point screams "Go, Go, Go". But because there's no clickable door to leave, the reader stays engaged.
- Writing for the vacuum: Do Unto Others...
- Support Cases and Documentation: Using support cases as inputs in the documentation maintenance phase.
Language and Grammar
- Of dots and curls - Part 1: Once upon a time, in a hut far into the woods, there lived a little boy called Comma.
- Of dots and curls - Part 2: The story continueth.
- Of dots and curls - Comma blurb: Limerick
- To Hyphenate or No: Small exercise.
- Money Matters (spot all nouns): What we document is going to be translated into 10 different languages, if not more.
- Word Mutants: The Washington Post's Mensa Invitational had asked its readers to take any word from the dictionary, alter it by adding, subtracting, or changing one letter, and supply a new definition.
- Style Quiz - The Economist: An old link.
Career
- Building a portfolio: A portfolio is your business card - it plays a large role in determining whether you get that interview call.
- Matter of ownsership (ethics): It is extremely bad behaviour to use a company's resources (authoring tools, documentation infrastructure) to create something and show it off as a sample without seeking the company's permission first.
- I want to be a technical writer: "My sister has decided to take up a full time career in technical writing. She is good in English and was a science student in her postgrad. She's been a stay-at-home mom all these years. What does she need to do?"
- What is technical writing: In less than 100, 50, and 20 words.
- The Covering Letter: Hiring managers of "hot" companies must be getting tons of these. What can I do to make my covering letter interesting enough to make them click that link that takes them to my actual résumé?
- The Expert and I: "Oh, we are all there to help you", grand sweep of the arm indicating the entire doc team. "Besides, for your product, there’s this SME whom you can ask if you need anything."
- What am I: I am a technical writer. Eh, what? What's that?
Community
- Harvest, separate grain from chaff, release to market: In 2008, the TWIN mailing-list archive had over 35,000 posts. These posts represent the accumulated knowledge of a community sharing and learning from its members. However, searching the archives was not easy. So was born the TWIN e-book compilation project - so that the info was accessible.
- How to mechanise the harvesting: Or, how to eliminate labour-intensive work in the TWIN e-book compilation project.
- Documenting Mjrz.net: A short post that records the writing of a small Help for a SourceForge project. The project has, since, ceased to exist.
- Translating WikyBlog to Bengali: A 2-line post that records the activity.
- Documenting TransProCalc: A short post that records the writing of a Help for a small financial tracking software.
Obiter dicta
- Play, play: Technical writing crossword.
- Wishing my blog readers a happy 2009: A bulleted list, mostly.
- Of crystal balls and a view: Peeping into the future.
- Blog's on Alltop: A 1-line news post.
- Genesis and a prize: In the beginning, there was the Word - a link to my blog post that won a prize.
- Translating Tagore: A post announcing a prize I won.