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

learn more… | top users | synonyms

2
votes
4answers
220 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
116 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
506 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
64 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
284 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
591 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
204 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
155 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
205 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
123 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
239 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
64 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
102 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
227 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
94 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
232 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
186 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
270 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
2k 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 ...
7
votes
3answers
428 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
426 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
256 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
278 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
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
2answers
267 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
122 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
86 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 ...
26
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 ...
3
votes
3answers
708 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
223 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 ...
3
votes
2answers
266 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
2k 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
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 ...
2
votes
1answer
109 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
130 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 ...
4
votes
2answers
939 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 ...
2
votes
2answers
104 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
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 ...
2
votes
3answers
82 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. ...
1
vote
1answer
75 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
58 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
4answers
220 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
220 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
548 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
144 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
1answer
337 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 ...
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 ...
4
votes
5answers
318 views

Using uncommon abbreviations

Something which I see all the time in (popular) science writing is the use of abbreviations to indicate concepts. For (a made up) example: So when we're dealing with Anachronistic Meta Mechanics ...
1
vote
1answer
156 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 ...
3
votes
1answer
2k views

How to write time duration correctly

Within a user manual, I need to convey the maximum time period allowed as "365 days 23 hours 59 minutes 59 seconds" - are commas expected between each component? Is the word "and" expected before the ...