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

learn more… | top users | synonyms

1
vote
1answer
35 views

When should I use italics in scientific writing?

I noticed that proper nouns, such as names of theorems or techniques are often set in italics in scientific writing but not always. Are there rules about it, for example each proper noun should be set ...
2
votes
4answers
85 views

How to reference a figure from text in a technical document

I'm preparing technical documentation for some software. For the installation, there are lots of screen grabs and they all have Figure x captions. What's the correct styling and means of referencing ...
0
votes
1answer
63 views

Looking for sites that describe minimalist writing for technical content

I'm looking for a site or sites that describe minimalist writing (http://en.wikipedia.org/wiki/Minimalism_(technical_communication)). The Wikipedia article is so minimalist it doesn't provide such ...
0
votes
0answers
14 views

Framemaker/ Software Question [migrated]

I have just started documenting a purchasing/warehousing/billing/sales/accounting application - a real monster! It is being deployed to multiple sites and is modified for each site. This means the UI ...
2
votes
2answers
60 views

How does one avoid incomplete changes to documentation?

Having encountered errors in technical documentation that almost certainly came from incomplete editing after copying from earlier documentation, I am curious about what techniques can be used to ...
2
votes
2answers
99 views

When is a screen shot really useful in training documentation?

Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screen shots when the ...
3
votes
2answers
120 views

Present tense in user manuals

I am writing a user manual for an IT system. And inside the user manual I have sentences such as: Users can delete Servers that do not have Customers assigned to them. Is the use of ...
4
votes
1answer
52 views

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 ...
5
votes
1answer
193 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 ...
10
votes
3answers
241 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 ...
4
votes
1answer
307 views

Bullets vs. Numbering: which to use when?

A writer can either choose to use bullets or else stick to conventional (or in certain cases non-conventional) numbering. Are there set guidelines about when to use what? Is the use of numbering ...
0
votes
5answers
119 views

Struggling to writing in English

I always struggle to write my ideas in English. Structuring my work/idea when it comes to writing leaves me blank. Even when I'm very clear about what I want to write, I will still struggle with ...
2
votes
3answers
117 views

Thesis writing: how to address “self”

This came up when I was writing my thesis: Usually it is recommended that when writing a thesis, one sticks to passive voice and use sentences that read like "The study showed the effect that blah ...
5
votes
1answer
168 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 ...
4
votes
3answers
102 views

Marking a chart that is not based on real data

I want to include a chart in my thesis to visualize an idea but the chart is not based on real data, it just helps me to explain a concept. How can I label it so it's not confused for actual data. It ...
2
votes
1answer
69 views

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?
0
votes
2answers
51 views

How should I handle repeating parts in a technical 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 engineers. ...
3
votes
3answers
52 views

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) ...
1
vote
4answers
127 views

What are the tool choices for producing technical documentation in PDF and web site ready HTML?

My company currently maintains our technical documentation (User's Guide) in Google Docs. With each release I produce a PDF that we host on our website. Here are the features of Google Docs that work ...
3
votes
3answers
88 views

How can we make compiling release notes less chaotic?

Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important ...
3
votes
2answers
71 views

What is a reasonable amount of time to spend writing a product overview?

I have plenty of writing experience as an academic and as a technician but am new to technical writing per se. A retailer of engineering equipment wants me to write unique, user-friendly content for ...
2
votes
1answer
102 views

Can Google Docs be used for technical product documentation?

My company is hiring a contract technical writer to improve our product's documentation. As the maintainer, I'm currently using Google Docs, and very happy with it's collaborative nature (multiple ...
4
votes
1answer
179 views

How can I prepare for a career in instruction writing and editing?

To technical background authors (e.g. Isaac Rabinovitch) who would possibly work in teams with non-technically trained writers: How can I prepare myself to be able to do what you do? How can I ...
6
votes
2answers
136 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 ...
4
votes
5answers
584 views

What are the advantages of different date formats in resumes and CVs?

I've seen a somewhat related question, but it doesn't answer my question quite right. Say you're writing an event that happened on a single day, and you need to put it in your resume or CV. So how ...
6
votes
3answers
190 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 ...
2
votes
3answers
118 views

Best way to write an article professionally

Is there any widely accepted step by step method for writing a creative article in a professional manner. I want to improve my English writing skills in relation to creative article writing. I read ...
7
votes
6answers
419 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. ...
1
vote
2answers
250 views

To translate a novel with Westerner's point of view

I am an Easterner. I have been translating a novel, that is originally written in my native language, into English. During the process, I have also been learning about cultural things, meant to ...
1
vote
1answer
181 views

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 ...
5
votes
3answers
1k 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
2answers
127 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 ...
6
votes
2answers
112 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 ...
4
votes
2answers
59 views

Should subsection headings sometimes repeat section headings?

In a technical or scientific text, such as a PhD thesis, should headings for (sub)sections be complete and sometimes repeat information from the headings of the levels above, or is it sufficient to ...
23
votes
6answers
1k 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 ...
5
votes
3answers
247 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 ...
3
votes
3answers
542 views

Is there anything like 99designs for text writing?

I'm not a writer, but a technical oriented entrepreneur.. One of the barriers I always run into is that I'm also the lead guy for providing the content for marketing gigs, speaker bio's and website ...
11
votes
2answers
207 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 ...
2
votes
2answers
170 views

API reference doc: best practices for describing opaque parameters?

The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool ...
2
votes
1answer
1k views

Mashery vs. Apigee

I was wondering if anyone could lend some advice as to the pros and cons between using Mashery versus Apigee for documenting an API? I have do some evaluating and have about 2 weeks to come up with a ...
8
votes
8answers
1k 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 ...
2
votes
1answer
69 views

Metrics for assessing the persuasiveness of a paper?

Are there any known variables to measure, or questions to ask in survey, in order to asses the persuasiveness of a paper? For example, I'm not sure if omitting a section from my paper might actually ...
1
vote
0answers
94 views

Using the Minto Pyramid

Using the Minto Pyramid, should I order the paragraphs of my paper by going through the rows of the pyramid like this? Thesis > Why > How > Where > A > B > C > D > E Or should I start at the top ...
6
votes
3answers
286 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 ...
4
votes
2answers
747 views

What is the best way to learn technical writing?

I have a moderate level of skills in technical writing (TW) having gone through graduation in engineering. I was wondering what would be the best way to sharpen my knowledge. I am also interested in ...
5
votes
4answers
557 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, ...
5
votes
4answers
384 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 ...
2
votes
2answers
93 views

How to represent dependencies in outlines

The bulk of my writing consists of technical papers, reports, notes, and memos. Because of the mathematical nature of my work I spend a lot of time writing definitions, and it is very important that I ...
13
votes
6answers
1k 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 ...
2
votes
3answers
78 views

Introducing the next sub-section or not?

I am writing my phd dissertation in a technical field and I have a question. When in the same chapter, I finish a section and want to connect it with the next section I am not sure what is better. ...