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:

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:

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