Deb Slutzky just joined the HATT list and posted a question about what specific files to provide for her RoboHelp project to foreign companies that will rebrand and translate the user interface and help files for the software she documents.
Colum McAndrew responded with the recommendation to "At the end of the day I wouldn't worry about only providing the exact files. Just give them the source files in their entirety and let them use whatever they need."
And then I chimed in with this:
I agree with Colum - give them every file in your project directory.
I would add that you have the opportunity to make the life of the person that takes your files a little easier by using comments in your CSS and in your HTML files. For example, when I was generating WebHelp to be deployed for a Desktop-based app, I couldn't link directly from a HTML file to a PDF because the PDF didn't have Mark of the Web (MOTW) so I had to create a HTML file for each PDF that simply embedded the PDF file. So, if you look at the code, the syntax to open a PDF would look weird because it was actually linked to a HTML file. I put notes in the HTML file that embedded the PDF. The way that project was structured, any link to open a PDF went to a central "Print Documentation" HTML file so I also added comments in the code on that page as well to explain what was happening. Do the same type of thing in your CSS file to indicate when specific CSS styles are being used. For example, in that same project, I created a span class for each UI element - check box, button, screen, etc. - so that I could control the appearance for every instance of that UI element. If I wanted to make all buttons bold/italic on Monday and then got feedback that they should only be
bold, not italic, I could change the definition for the button class in my CSS file and every instance of button would become bold. You can also include examples in the CSS file that could be helpful.
Even if you are not shipping your project off to be translated, I would include comments in both your HTML and CSS files.
No comments:
Post a Comment