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

learn more… | top users | synonyms

2
votes
1answer
32 views

How do I approach rewriting an entire user guide in an agile environment?

I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The ...
3
votes
0answers
52 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 examples ...
1
vote
3answers
117 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
0answers
9 views

Term for advancement through medical anomalies [migrated]

I'm looking for a term to describe when a medical advancement is achieved through, for example, a natural immunity to a disease. For example, the Berlin Patient, who is naturally immune to HIV may ...
2
votes
3answers
164 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
4answers
685 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
64 views

Template for IT technical report?

I'm looking for a template or guidelines for how to write a technical report. The report is IT-related and intended for a project manager to review the work of the investigation of a IT-related ...
3
votes
4answers
97 views

Is this title suitable for a chapter section?

Suppose I am writing a chapter about some deep technical subject (say, for instance, "boolean variables"). This theme is riddled with idiosyncrasies and misunderstandings, so I would like to present ...
7
votes
3answers
155 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 ...
0
votes
1answer
29 views

Write a presentation of a dissertation [closed]

we have made a dissertation about a type of insect called Pine Processionary Moth. we have upplied some statistical methods on it: data analysis and cluster analysis!! we have almost finished, but i ...
5
votes
2answers
152 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 ...
4
votes
3answers
253 views

Online technical writing classes

anyone aware of or can recommend online training courses for technical writers to improve your technical writing skills? I'm looking for courses that provide video or audio lectures, and teachers ...
6
votes
5answers
539 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 ...
5
votes
4answers
357 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 ...
3
votes
3answers
177 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 ...
0
votes
2answers
115 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 ...
15
votes
5answers
740 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 ...
1
vote
4answers
365 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 ...
1
vote
1answer
34 views

Author order and grouping on technical document

This question pertains to author/contributor order and grouping on a technical document. I performed tests on some equipment and had two other people directly involved. My boss and his boss need to ...
2
votes
4answers
108 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
2answers
82 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
216 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
59 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 ...
10
votes
3answers
258 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
343 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
137 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
137 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
181 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
112 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
92 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
53 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
60 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) ...
3
votes
3answers
139 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
82 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
121 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
180 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
168 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
726 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
230 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 ...
7
votes
6answers
420 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
252 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
190 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
150 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
114 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
68 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 ...
24
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
290 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
595 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
214 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 ...