Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.

learn more… | top users | synonyms

54
votes
13answers
4k views

What's the modern way to handle gender in tech writing?

Back in my day, I was taught to use masculine pronouns. The user chooses a password, and then he types it in the text box. I'm fine with that. but a male coworker insists on using he/she, ...
25
votes
6answers
2k views

Writing first programming book

I was recently asked if I was interested in writing a book for a pretty reputable publisher, which of course I accepted. I am not a writer by trade, I am a software developer with some technical ...
22
votes
10answers
539 views

How can one make technical issues more accessible to a non-technical audience?

Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc. Lately, I find that some of the topics I am trying to present are much more technical ...
16
votes
6answers
865 views

Best practices for maintaining documented code examples?

A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically ...
14
votes
14answers
1k views

Is it okay to call the reader's target audience stupid?

I'm a tech genre author, and have already published one book on Android development. However, this book was focused more on the developer of the apps, than the user. Now I'm working on my second ...
13
votes
6answers
2k views

Should one use the legal “shall” in requirements documents and specification documents?

At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of ...
11
votes
6answers
2k views

Technical Writing Software

I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such as ...
11
votes
4answers
3k views

Writing a programming book: how to present directory structures

What is good/preferred way of presenting directory trees in programming books? My main criteria are following: It should be readable and intuitive It shouldn't take too much page space It ...
11
votes
2answers
219 views

How do you build good per-book *and* global indexes?

For our SDK, we generate individual documents (PDFs) and one big HTML doc set (CHM file) from the same Docbook source. Each book has an index, and the HTML version has an integrated index that is the ...
10
votes
3answers
274 views

How to write to accommodate subsequent automatic translation

The texts I am writing will be translated by people who are not experts in the topic and in some cases by a machine with next to none human editing afterwards. What strategies should I employ to ...
10
votes
5answers
3k views

How much time do you spend writing one page on average? [closed]

I'm writing a technical book about one programming technology and would like to compare how much time other authors spend on one page (on average). I rarely write a page and am done with it, quite ...
10
votes
3answers
285 views

Is it legal to write about trademarked material and use the terms?

I am contemplating writing a technical book (and probably self-publishing it) on a proprietary programming interface for a well-known software package produced by a very large company. The company ...
9
votes
10answers
285 views

An alternative to saying 'users' when describing features

I'm creating some copy describing new web-app features for a number of different audiences (users, managers of sections of the site, owners of sub-sites which use our platform etc.). I'm finding ...
9
votes
13answers
1k views

Does a technical writer need a technical background?

Does a technical writer need a technical background?
8
votes
8answers
2k views

Good Outlining Solutions For OSX?

I write technical non-fiction and find that I cannot write well without first constructing a detailed (10-20 page) outline. Are there any good outlining solutions for OSX? Apps? Templates in Microsoft ...
8
votes
3answers
519 views

What are the key skills for a new technical writer?

For those that are just starting out, what are key skills they should have or learn to be a good technical writer?
8
votes
6answers
901 views

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, ...
8
votes
2answers
270 views

Good Examples of and Practices in Code Documentation

I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents is to imbibe good examples. Can you recommend any ...
8
votes
3answers
153 views

Good tools for writing (game) manuals and sourcebooks

As I had asked in another part of Stackexchange (didn't know about this part until some comments there) I'm writing manuals (mostly for computer games, but in addition to this also for tabletop games, ...
8
votes
3answers
171 views

How do you track dependencies for your co-authors?

I and one or more co-authors, sometimes geographically distributed, are working on a set of related documents. Sometimes I will make a change in my part that has effects on someone else's part; this ...
7
votes
6answers
422 views

Quality of my blog writing [closed]

I came here from Jeff Atwood's blog where he mentions that writing a blog can clear your own internal thought processes and that you should take feedback about your writing so that you can improve. ...
7
votes
5answers
885 views

Demo data in screenshots! What are the best practice?

My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making ...
7
votes
1answer
3k views

Citing Myself As a Source

I'm writing an academic paper on ethics in robotics. I have a previous paper that I wrote and would like to use material from it. If I use the material from this paper, that I wrote, do I need to ...
6
votes
3answers
345 views

How to start a technical book?

Well, I am a experienced software developer and looking at question made by friends that are learning, questions over the internet and StackExchange, I noticed that I eventually could help more people ...
6
votes
8answers
505 views

Verbosity: when's enough enough?

In corporate life I've come across two general styles of writing: terse and cryptic or long and complete. In my own writing I tend to go too much in the "explain all possible interpretations" ...
6
votes
3answers
429 views

In end user documentation, should screenshots come before or after the text that references them?

The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions for or conceptual explanations of the ...
6
votes
2answers
426 views

Breaking Into Technical Writing - Where to Start (from a programming background)

I'm currently in the process of expanding my company from doing coding & web development to more technical writing and freelance tech journalism. Although my background is mainly in technology, ...
6
votes
2answers
231 views

Using LaTeX with publishers?

Background: Im working on a rather long instructional book, and have just started trying to use LaTeX. The book doesn't have any scientific notation in it, and most of the diagrams I made in other ...
6
votes
2answers
812 views

Should I prefer long or short sentences in scientific writing?

Currently, I am writing papers with rather short sentences: About half of them contain around 20 words, about 10% to 20% even less. I am doing this for three reasons: I find short sentences easier ...
6
votes
4answers
520 views

Which goes first: summary, background or justification?

I am trying to write a long expository piece and cannot figure out which information should come first. Here are three candidates: A summary/abstract lists the main points, without necessarily ...
6
votes
2answers
119 views

Standards for representing user interaction

I am responsible for developing internal IT documentation but have only begun my scratching the surface on technical documentation. Is there a standard or best practice for the following: Example ...
5
votes
3answers
2k views

Does reading books help writing skills?

Just what the title says. I decided to improve my writing skills only for blogging purposes (for starters and no, it's not a part of new year's resolution). I am also not really good at writing (i.e. ...
5
votes
5answers
191 views

How to write about things which depend on each other

I am writing a technical documentation about a product. Now problem is there are many interrelated and interdependent concepts. I am just confused how to put them in order. I mean if I talk about ...
5
votes
6answers
289 views

Book recommendations for writing better technical papers

My employer has presented me with two books to read to help me write better technical papers and emails. Essentials of English Grammar and Handbook of English Grammar and Usage. I have read through ...
5
votes
3answers
313 views

Is the idea of single-sourced documentation dead?

Is the idea of single-sourced documentation dead?
5
votes
1answer
453 views

How to get a programming book published

So I feel I'm a pretty good programmer in my area of expertise. Whats the process for writing a book about my niche and getting it published?
5
votes
4answers
500 views

How can I write better code-based reference documentation for programming interfaces?

Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what ...
5
votes
3answers
174 views

How to leverage social proof?

How can one use social proof as an argument without sounding like "just because everybody is doing it so should you"?. My problem is trying to demonstrate with social proof that trendy ...
5
votes
5answers
151 views

Interesting and easier-to-read alternatives to the scientific academic article

Short version: What is an equally informative, but more interesting alternative to typical academic-article-style scientific writing? Longer version: I love writing, I do a lot of it – fiction and ...
5
votes
6answers
464 views

Does this feel like natural English?

Although I'm pretty confident in my English, I'm not a native English speaker. I need to write a short introduction for a symposium; I'd like to know if you think this paragraph feels like 'natural' ...
5
votes
3answers
1k views

When is it acceptable to use the first person (“I”, “we”) in technical reports?

When is it acceptable to use the first person ("I", "we") in technical reports?
5
votes
3answers
251 views

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 ...
5
votes
2answers
257 views

Best Tool to Create User Guides

We are planning to create a user guide for internal use only. It's 150-page document in Word for a self-developed SW tool. The user guide will require constant update. No translation is needed. We ...
5
votes
4answers
321 views

How can a new writer make a realistic estimate of his work rate?

This question relates to my earlier question Habits and routines for my first tech writing job which I was told to split into two parts. My first technical writing / translation gig starts soon. A ...
5
votes
3answers
430 views

Overusing “the” and “I”

I'm not a native English speaker, and I find that my English writing contains too many definite article "the" when writing scientific reports, and too many "I" when writing in informal settings (like ...
5
votes
2answers
141 views

How should I document a database schema?

I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look ...
5
votes
2answers
368 views

How do you introduce terms?

There's a few different styles for technical (academic) papers. Which is the preferred style to introducing new technical terms? For example, here is a paragraph I have that I don't like, because I ...
5
votes
1answer
191 views

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 ...
5
votes
2answers
271 views

Why are license agreements, disclaiming letters and others written with capital letters?

We know that reading sentences with capital letters is hard. I noticed that some documents are still written with capital letters. Why are license agreements, disclaiming letters and others written ...
5
votes
2answers
210 views

How can I prevent, or work around, unfortunate hyphenation in critical words?

In technical documentation, sometimes the tool's automatic hyphenation makes a bad break in the middle of a term, like the name of an environment variable or function. In these cases I would rather ...