Online groups, spring 2014
Career improvement
A member worked at three engineering companies where he was the only technical communicator. Although other employees had a career path such as from Design Engineer to Senior Design Engineer, and then to Principal, there was no similar career path for technical communicators. Does a solution to the problem exist?
Many members agreed that technical communicators do not have good career options. Some members suggested that becoming a freelance technical communicator is a good solution.
If you receive the money that you want, and if you are happy with your work, do not worry about your job title. Typically, in a small organization, one technical communicator is sufficient. Therefore, you are not likely to be the Technical Communications Manager.
Many members think that their managers do not value the work that they do. Many managers think that technical communicators are a cost, not a source of revenue.
Many companies supply documentation only because customers expect documentation or to conform to regulations. The requirement to conform to regulations is an advantage to technical communicators. "The humble TA suddenly becomes a key stakeholder."
To increase our status, we must do these things:
- Explain the financial value of the work that we do. One member wrote, "Terms like 'user advocacy' and 'understanding our audience' are fine, but they are meaningless to business leaders. Employers want to know how our work can have a positive effect on the organization's financial results."
- Develop our professional skills. The new CPD scheme from the ISTC is a good way to do this. Possibly, the Skills Framework for the Information Age is useful to some technical communicators (www.sfia-online.org).
Light text on dark background
Some documentation has light grey text on a dark grey background. The documentation looks good and has the same colours as the related software. Will the style cause problems to people who read much text at one time?
Some members think that light text on a dark background will cause problems for some people. One member can read white text on a black background easily, and thinks that some people will like the colour style. However, the best option is to do usability testing, because then you have data, not only opinion.
Members suggested these resources:
- 'Blinded by colour', Max Williams, Communicator, autumn 2011.
- 'Minimising barriers to reading for people with dyslexia', Melanie Jameson, Communicator, winter 2001.
- https://en.wikipedia.org/wiki/Light-on-dark_color_scheme
- https://snook.ca/technical/colour_contrast/colour.html
- www.colourblindawareness.org/colour-blindness/types-of-colour-blindness/
- www.dyslexia-malvern.co.uk/melanie
Syntax highlighting
Syntax highlighting is a feature of text editors that shows different types of text with different colours (https://en.wikipedia.org/wiki/Syntax_highlighting). Usually, software developers use syntax highlighting to make their code easy to read. For example, comments and function names have different colours.
Frequently, API documentation contains examples of code. A member asks whether syntax highlighting in documentation is useful. Does syntax highlighting increase the readability of text?
Members agree that syntax highlighting increases readability, because it shows what a software developer sees in a text editor. Additionally, to show clearly the difference between example items and the structure that you are demonstrating, use terms such as 'myObject'.
The member who asked the initial question wants to use syntax highlighting in Word documents and in online documentation for different programming languages such as PHP, Ruby, and Python. He does not want to add syntax highlighting manually by applying styles in Word documents or by adding formatting code to HTML pages. He wants to automate the task, but the syntax highlighters that he tried did not give good results.
For online help, a member recommended Google Prettify, which is "a JavaScript module and CSS file that allows syntax highlighting of source code snippets in an HTML page" (https://github.com/googlearchive/code-prettify).
RSS feed