Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.

Using single source document for GUI descriptions and tool tips

Hi All,
I have few questions related to few problems which we face every now and then. 
1) How do you manage the GUI Descriptions (labels and tool tips)? 
2) Is there any way to use the single source document to create the information required in the GUI?

For example, as a technical writer, you create documents which already have the information of various fields (buttons, text fields, etc.). Is there a way to use this information by the developers to design the GUI. And most important, it should be automated.



  • KatriinaKatriina Posts: 1

    Depending on the way the software you're writing about is coded, you might be able to extract the GUI labels and tooltips. Just being able to extract them (e.g. to a csv -> excel) might help you go a long away in checking, copy-editing and harmonizing them (e.g. in Excel, you can easily sort alphabetically, which can help you spot if there are variation in spelling, typos etc.).

    Furthermore, once you have the export, you might then be able to convert that to some kind of publishable document which you could add as an appendix/reference in your documentation set, if that's what you're after. Unless you're a coding wizard type of tech writer yourself, you'll probably need to get one of your developers/coders do all this for you.

    I work with a Java-based product where all the UI labels and tooltips happen to be stored in a database. I can't code for my life nor know the details of how to extract anything or then turn it into Excel, XML etc. So, one of the developers has built a Ruby based script that extracts all the label and tooltip strings, produces a csv/Excel file out of them and then builds an XML document (with mainly tables) that our documentation tool eats. Once I get the XML files, I can build a PDF/HTML output that looks the same as all the rest of our documentation. The developer who created the script chose Ruby (and the various text processing 'gems' to go with it) because he knew it could do the job. All I did was to provide a "template" of what I would want the output to look like (an example XML files where all the style names etc. were shown) + pointers to the XML API of the documentation tool.

    So it was a kind of problem solving challenge for the developer in question + management supported him spending time on it as the ROI was pretty attractive: have a UI reference document that can be generated with few clicks of a button, and even better, it always reflects what exists in the product, i.e. there's no 'TechWriter-got-it-wrong' danger in the picture.

    So my recommendation is that you describe your problem / the desired output to someone in the development team and ask them to suggest a solution. To my understanding, most software is built in a way that the UI strings can be extracted (e.g. if your product is localized, the translation process must be able to access the strings) + most documentation tools have an API that supports 'machine produced content'.
Sign In or Register to comment.