Tag Info

New answers tagged

0

Having taken the considerable amount of time that it takes to learn how to use DTP software (most recently when I had the job of laying out a magazine) and knowing what results you can achieve, I would definitely recommend you just use a word processor such as Word or Open Office. What you are doing doesn't need extremely precise control over layout, ...


3

I think MS Word and Open Office would be the obvious candidates. MS Word pretty much dominates the market. Open Office is there for people who just want to rebel against Microsoft. I'd need a very good reason to use anything else, as to function in a Western business, government, or academic environment these days you pretty much have to use MS Word at some ...


0

For Mac, take a look at BBEdit. In particular, it has fully supported GREP search-and-replace functionality. There's an e-book that can be bought with the BBEdit product, which is highly recommended because it provides usage examples for the GREP functionality. For Windows, try Notepad+. In addition to the base product, there are any number of plug-ins that ...


3

I am not a lawyer and this is not legal advice. First, check any license terms that accompany Company S's documentation. They might have published it with the intention that other vendors will incorporate it (e.g. some Apache platforms), or they might not intend that but allow it under their license (e.g. Stack Exchange, or anything else that uses the ...


1

This is a legal issue. Specifically, a copyright issue. Assuming we are talking about the United States, company S owns the copyright to their documentation. It is illegal for company M or anyone else to incorporate company S's documentation into their own without obtaining the right to do so from company S. Consult an attorney. Also, take a look at The ...


4

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

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 ...


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 ...


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 ...


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.



Top 50 recent answers are included