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
25 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 ...
0
votes
1answer
56 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
96 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 ...
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
186 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 ...
4
votes
1answer
300 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 ...
3
votes
2answers
117 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 ...
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 ...
0
votes
5answers
118 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 ...
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
4answers
81 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 ...
2
votes
1answer
68 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?
3
votes
3answers
50 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) ...
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
87 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 ...
1
vote
4answers
122 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 ...
2
votes
1answer
101 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 ...
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 ...
6
votes
2answers
134 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 ...
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 ...
6
votes
3answers
185 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 ...
1
vote
1answer
180 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
2answers
126 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
58 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 ...
5
votes
1answer
167 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
3answers
244 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 ...
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
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 ...
5
votes
4answers
379 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 ...
6
votes
3answers
285 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 ...
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 ...
1
vote
1answer
72 views

Multiple tasks and a step by step tutorial

To my knowledge step-by-step tutorials should have the form of a ladder, where you describe how to get to a place step by step– accomplishing a single task at the end. Is it possible to accomplish ...
0
votes
2answers
55 views

What is the correct word/term that needs to be before the names of the maker of the project?

I am doing a project with one other person, we have finished the project and we are working on a cover page. We are not sure what to write out before our names, we have thought of a couple of ...
4
votes
5answers
579 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 ...
5
votes
4answers
548 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, ...
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 ...
4
votes
4answers
171 views

How can I consistently distinguish among tables, fields, and records in a database?

I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows). I spend a lot of time discussing tables and ...
4
votes
1answer
139 views

singular or plural for index entries

I am in the final stages of writing a book and currently I am preparing the index. Are there any rules whether index entries should be listed in singular or plural? Currently I have Markov chains, ...
5
votes
1answer
287 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?
4
votes
3answers
137 views

How can I express this fragment more clearly and concisely?

For the 'who is this application for' section of an application user guide, I have the following alternatives, I'm not happy with either one. How can I convey both elements more clearly and ...
2
votes
2answers
8k views

Multiple authors in MLA header

I'm writing a group paper and I was wondering whether there's a correct way to list multiple authors at the top of the first page in MLA format. Normally the header would look something like: My Name ...
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 ...
2
votes
1answer
205 views

In what narrative mode should you explain a process or task?

I want to explain a psychological and behavioural process to someone via email. I start off in first-person and speak to them in second-person, but what do I use when I want to explain a process ...
1
vote
1answer
147 views

combining sentences

I want to say couple of this within one sentence. so my sub sentences would be: We removed the vertical features from the classification process. The removal of vertical features enhances ...
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. ...