Writing Stack Exchange
Writing Stack Exchange

Questions tagged [technical-writing]

Documentation, tutorials, training, user guides, installation guides, design documents, and all other types of technical documentation in any domain (not just software).

For questions specific to software documentation, see .

491 questions
14
votes
8 answers

Which is more readable - array of ints or int array?

A similar example is field of carrots or carrot field. The latter feels better to me, especially in the carrot example, but when asking colleagues they preferred 'array of ints'. I'm not a professional writer, so I don't know if there is a clear…
Nimrod Fiat
  • 251
  • 2
  • 5
11
votes
6 answers

Ways to improve your writing skills

As a CS major I've learned that knowing how to write is critically important, but, I'm not really sure how to improve my writing skills. I'm currently trying to write a tech blog in English, but, whenever I sit down to write, it just reminds me of…
Wilbeibi
  • 213
  • 1
  • 5
7
votes
4 answers

How can you write less to say more?

Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader. In technical writing the later is very typical (at least for me), one can tend to over-explain and get the adverse effects out…
dukeofgaming
  • 273
  • 1
  • 7
7
votes
2 answers

Is writing "Bad practice"-notes in tech guides bad style?

So, I'm in the process on writing a hardening guide for Windows 10. Similar to http://hardenwindows10forsecurity.com/index.html, but different in scope and style. I wondered, if informing about "Bad/Worst Practices" would be a thing that should be…
CuttingWide
  • 73
  • 4
6
votes
1 answer

Outlining for white papers

I used to write technical white papers on different technologies. There should be some rules for writing professionals, some home work that needs to be done. I have never gone through any professional writing course, so I feel that I should go for…
gyansangrah
  • 63
  • 2
6
votes
1 answer

Does the only figure in a document get labeled as Figure 1?

If a document references only one figure, is it identified as "Figure 1" or no number assigned?
Lizzi Williams
  • 61
  • 2
6
votes
3 answers

Is the idea of single-sourced documentation dead?

Is the idea of single-sourced documentation dead?
Ralph Gallagher
  • 8,706
  • 5
  • 38
  • 61
5
votes
4 answers

Do Decimals Bounded Between 0 and 1 (inclusive) Need a Leading Zero?

For a variable bounded between 0 and 1 inclusive, [0,1], should I use a leading zero when quoting a number? E.g. the probability of rain is 0.5 or .5 (I realize this should technically be 50%, but I hope you accept the premise of the question).…
EconomiCurtis
  • 153
  • 3
4
votes
2 answers

Is it OK to repeat the word implied by an acronym?

Say, we have a sentence like that (found on the web): The ICAP protocol specifies extensions allowing a client to report the IP address of the client and the origin server involved in the HTTP transaction. ICAP means "the Internet Content…
Peter S.
  • 41
  • 2
4
votes
3 answers

What's a good replacement for the phrase "best practice"?

In technical writing the phrase "best practice" is often used to suggest that something is more accurate than other things. However, that's often very subjective, requires specific context, and suggested practices change over time. In the software…
Tom Resing
  • 171
  • 1
  • 6
4
votes
5 answers

How much detail when writing technical documentation?

As a software developer, I often find myself writing my own technical documentation and user guides. How much detail should be put into this documentation? When is it too much detail? EDIT I'm stuck on a user simply being able to follow a linear…
Jon Milliken
  • 151
  • 4
4
votes
1 answer

In a FAQ, should a question header take the form "Why does blah blah?" or "Blah blah happens, Why?" And why?

Whilst writing technical documentation, there is commonly a section on troubleshooting or frequently asked questions. I know a FAQ should be real questions - not ones the publisher thinks might be asked. But when wording the question header, should…
Roger Attrill
  • 141
  • 3
4
votes
1 answer

Can I use the same figure twice in a report?

Is it alright to use the same figure twice (but different figure number) in a report? If so, do I have to use separate captions, to avoid confusion in the table of figures?
Wet Feet
  • 143
  • 1
  • 1
  • 4
4
votes
3 answers

Should I have an introducing paragraph in every chapter of my description?

I'm about to write a technical description for an industrial process. The description will follow logical blocks, or blocks from the PFD of the process. This a sales document aimed at (mostly) engineers. My idea is to have a short paragraph at the…
mart
  • 183
  • 6
3
votes
1 answer

What are best practices when writing technical descriptions?

Occasionally, in my job as an engineer, I write process descriptions of the technology we are selling. Those are part of commercial offers, intended to win the customer. Those are bundled with drawings, technical offers and the like. We are selling…
mart
  • 183
  • 6
1
2 3 4