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

learn more… | top users | synonyms

1
vote
0answers
26 views

What is Content Testing?

What is Content Testing? Are there content testing tools available or they are simply tested manually for quality.
2
votes
0answers
22 views

Graphical presentation method nomenclature

I'm part of a technical documentation team where I'm suggesting the document designers different methods for graphical presentation. Each time I need to talk about a method I have to look around and ...
2
votes
2answers
40 views

How to create a functional document for in-house reference?

I'm the only technical writer in my company with 2 years of experience. I have been assigned with a task of creating a functional document for a web-based (FMCG) product which has been around a long ...
1
vote
5answers
123 views

What's the best text editor for a technical reference manual?

It is my first time writing tech manuals and I don't know what to use. Some people recommend me LATEX but I think it's too complex. I basically need a text editor that let me: Type latin characters ...
2
votes
2answers
30 views

Ethics of incorporating a supplier's technical documentation into one's own documentation?

A company, M, buys components from company, S, to build into their product. Company S has technical documentation regarding safety and maintenance available in many languages and publicly available in ...
3
votes
2answers
53 views

What's the common practice for warranty chapters in technical manuals?

I'm working on a technical manual project for industrial machines and the original documents have some warranty warnings and statements at the beginning. We decided to keep them on the new documents ...
1
vote
3answers
62 views

Technical Documentation Voice Preference : “Active Voice” - “Passive Voice” - A Mixture of both

We are working on a technical documentation project which includes the rewriting, modernization, restructuring, enrichment of the content. I'm doing the content rewriting and translation parts of the ...
1
vote
1answer
53 views

Order of names in title

I and two other students are writing a proposal to a corporation to donate some equipment to the Electrical Engineering department at my school. When I put our names under the title of the proposal, ...
3
votes
1answer
48 views

Writing a PhD thesis. Question about (an informal) introduction

I am preparing scientific thesis for the degree of PhD. It is a mathematical thesis. It is usually very difficult to tell your colleagues and friends what are the things you exactly work on with ...
2
votes
3answers
64 views

How to structure a sentence containing long code examples?

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence ...
2
votes
1answer
30 views

Is the Microsoft Manual of Style appropriate for writing general IT related instructional documents?

I'm currently working for a company's IT department, and one of my tasks is to write documentation for common procedures that we perform, in order to get new employees acquainted with them more ...
2
votes
3answers
104 views

Ending a PhD thesis by saying “there is more to do”

I am ending the conclusion of my PhD thesis by saying something like this (not even remotely in these words): There was a lot of work gone in the thesis, yada yada yada, however there is room for ...
2
votes
1answer
78 views

Any advice on how to learn DITA for technical writing?

My situation is such that I will be looking for a new job next week as this contract ends. For a tech writer, it is good to have DITA on the ole' resume. So, I just wanted to know if anyone has a site ...
1
vote
3answers
70 views

Technical writer degree with an English BA?

I'm desperately trying to get out of my dead end Federal job. I have a BA in English and a love of a lot of different topics, including several science fields. I would have Majored in science if I ...
4
votes
1answer
392 views

in English, is it necessary to capitalize after a colon?

I've seen that each language has its own rules when using the colon. In Spanish, it's not needed to capitalize: Los elementos incluyen: secado, lavado, etc. In French is the same, and even they put ...
1
vote
4answers
144 views

How to indicate the topic has been changed without using words?

I am writing an an article to share knowledge, not novel. Usually, when you change the current topic, at the beginning of the new paragraph you would like to use some transition words such as ...
3
votes
1answer
50 views

Is there any research about the efficacy of illustration and example placement in procedure writing?

In writing procedural documentation, I have the choice of writing the complete step-by-step instructions with references to an appendix of illustrations, For instance: 1. Do task 1 (see Fig. 1) 2. ...
1
vote
1answer
132 views

How much detail is considered enough for literature review of a research paper

I and a few of my friends are conducting a small research project to determine the prevalence of hypertension, where we live. I was hoping I could get an opinion on how to write our literature ...
4
votes
3answers
127 views

Software for keeping track of book edits?

So I'm writing a new edition of an old textbook, and I need some way of keeping track of what needs to be done, and what I have done. I could use paper - but I tend to lose that. Or even a plain text ...
1
vote
2answers
67 views

Documenting Agile Sprints

I'm responsible for documenting a huge ERP - its being changed from an old language to .NET. I'm the only one responsible for documenting ( and I'm doing it off-site - the developers' office is an ...
3
votes
2answers
136 views

What is the average cost of software for DITA authoring?

I'm looking to buy some software for technical document authoring with DITA. The tech writing group will have at least 5-10 users, writing 100-pages long documents for several products in various ...
1
vote
1answer
38 views

How do I build a better blog website? [closed]

I've spent the last few days building a website that I want to use a showcase for my written work, and as a personal blog. What fundamental changes should I make to improve a viewer's experience? The ...
1
vote
1answer
92 views

Copyright of examples used in books?

I'm getting into non-fiction technical writing (a blog, but potentially ebook or otherwise). Often the best technical advice come from dissecting and synthesising good and bad examples from the ...
-2
votes
1answer
75 views

How to write “number of cups per user” for short using symbols?

I want to insert a text segment in a figure in my conference paper. Like "number of cups per user", can I use #cups/user ? I think "cups/user" means an average value, right? What I need is a X-Y ...
1
vote
1answer
99 views

Use of Registered trademark

I'm writing a book on Windows and I need some guidelines. On the cover of the book, as part of the subtitle, may I include Windows® in it? Inside the book, do I have to use the ® every single little ...
-2
votes
2answers
85 views

Are there books to improve the style?

I've opened a question in another section: http://meta.programmers.stackexchange.com/questions/6911/is-this-question-possible-in-this-section The question is pretty unclear but for me is really hard ...
2
votes
2answers
526 views

What software is good for writing a technical book? [duplicate]

I must write a book for the university and I am looking for software. The style that I want is like the books of O'Reilly, Apress or Packt. I need: Insert a table of contents (automatic). Divide ...
2
votes
3answers
144 views

How to research and discover topic popularity and trends to determine topic selection for article writing?

I have been asked to write various technical and non-technical articles about computer usage, Windows usage (perhaps some Mac and *nix as well if they let me), Windows repair, and various other ...
4
votes
3answers
436 views

Do Decimals Bounded Between 0 and 1 (inclusive) Need a Leading Zero?

For a variable bounded between 0 and 1 inclusive, [0,1], should I use a leading zero when quoting a number? E.g. the probability of rain is 0.5 or .5 (I realize this should technically be 50%, but I ...
5
votes
2answers
216 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 ...
4
votes
1answer
96 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 ...
8
votes
2answers
392 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
169 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, ...
2
votes
2answers
78 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
120 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 ...
0
votes
1answer
32 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 ...
6
votes
2answers
291 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 ...
1
vote
1answer
39 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
3answers
593 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
2answers
307 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 ...
2
votes
2answers
122 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 ...
4
votes
3answers
347 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
65 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
4answers
604 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
660 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 ...
2
votes
2answers
556 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
286 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
209 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
157 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
124 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 ...