Tag Info

Hot answers tagged

3

Active voice is the appropriate choice for all types and sections of technical documentation, and for training and service manuals. The Microsoft Manual of Style is used by professional technical writers. The 4th edition (2012) says: In general, use active voice. Active voice emphasizes the person or thing performing the action. It's more direct than ...


3

Whatever results in the less convoluted and easier to understand syntax. Usually people find it easier to understand active voice. Even research articles are today usually written in active voice and avoid confusing self-reference-avoidance (do: "We conducted a study...", don't: "A study was conducted ..." [by whom?]). Machines are operated by persons, they ...


3

This is a decision you need to make in consultation with your company's legal advisors. The ability to defend against claims is affected by both what the warranty says and how prominent it is. A separate document or appendix that people are less likely to read might cause problems in this area. (Never mind that users are trained to skip past all that ...


2

I would put them at the end as appendices. That way they're part of the documentation but not in the way when someone goes to look up a feature. But I actually like the idea of having them as part of the documentation, because individual documents mean more moving parts, and a smaller physical document (like a warranty) can be easier to misplace than a thick ...


2

If one of you is obviously senior to the other in some relevant way, then put that person’s name first. If you are both reasonably similar in standing, then put your names in alphabetical order.


2

Often there is a difference between a thesis, as it is submitted to the examination board, and the book, as it is published. The version that you submit to the board of examiners must comply with the academic rules of your discipline. It will usually be written for an audience of experts. Ph.D. theses have to be published, but today you can publish it ...


1

My preference is for passive voice for reference material, some active for tutorials/howtos and whatever is easiest to understand for instructional or theoretical overviews. For example a mechanic changing a tire will check the manual for inflation pressure and lug torques (reference), a teenager will want a youtube video (howto), but an engineer will want ...



Only top voted, non community-wiki answers of a minimum length are eligible