technical-writing

When can "creating" and "declaring" be used synonymously?

Once in a while you stumble over a technical article where "creating" and "declaring" are used synonymously. E.g. declares an array of ints creates an array of ints But aren't declaring and creating two different things? Or does it depend on the context? ...

Corporate Wiki Organization - Technical Documentation

Corporations have documents describing various aspects of their technical systems, including: Custom Applications Custom Development Frameworks Third Party Applications Accounting Bug Tracking Network Management How To Guides User Manuals Software Tools Web Browsers Development IDEs Graphics GIMP xv Text Editing File Transfer n...

Using the word "you" in an user manual

I am writing a user manual and I have come to a discussion with a colleague. He says I cannot use the word "you" anywhere in the manual. Now I remember something about this at school but that was not for writing procedures. Also, doing some googling I observed that most tutorials where using it a lot. I would prefer using it but on...

Writing technical documentation: How to refer to a 'user'

Hi. I really don't know any better place than here to ask this, so here I go. I am writing techincal documentation for a small college project. A big question is, how to refer to a 'user'. I don't want to refer to it as a male since I will be targetting female students and it would seem unfair. Is it ok to call a user - 'it' Like: As...

Keeping Computer Science Writing Accessible and Eloquent

This question is particularly aimed at descriptions and explanations of what is happening in a computer program, as well as any general advice or approaches for undertaking technical reports in Computer Science at both undergraduate and graduate levels. You see, I am having particular difficulty in the best way to explain what is happen...

What "voice" should messages and documentation be written in?

I was writing some error/warning messages a while ago, for an application I am developing, and I was thinking - what "voice" do you write software text in, in general? There's several different categories of text that is included with software packages, including: Interface text - very small amounts of text like "OK", "Cancel", "Title...

Writing a tutorial for an audience with some background knowledge

At the moment, I am writing a JavaFX tutorial targeted at programmers with a solid grasp on Java. The idea is to give them an as-short-as-possible intro to JavaFX, focussing on the differences between Java and the JavaFX Scripting Language while at the same time skipping things which are identical in both languages. The problem is: it's...

Decent tool for producing a glossry of technical terms

I'm currently developing the front end of a new CMS for a digital streaming company, the main problem the project has is keeping track of the technical language that has sprung up around it. It currently involves around 60 staff in four countries, aside from a wiki (which has thus far failed to be kept up-to-date), anyone have any good...

Software Requirements Specification for Reports

Reports, generally, have the following components: Report title Physical location (repository, network drive, or web server file system) Parameters (hidden and user-supplied) Query (SQL) Security (roles and authorization) Formatting and layout (column order, static text, and images) Q.1. What else would you want to read in a technica...

Resources for writing good PHP documentation

I am getting a tool ready to make the source public. I would like to have it well documented for people who would use it as well as potential contributors. I am already using some rudimentary docblocks and some line comments for class variables. Currently I am using doxygen because it integrates into eclipse, but I am not wedded to it...