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
18 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
50 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 ...
16
votes
7answers
907 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
1answer
15 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 ...
1
vote
4answers
123 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 ...
12
votes
7answers
2k views

Technical Writing Software

I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such as ...
2
votes
1answer
44 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. ...
2
votes
3answers
89 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 ...
1
vote
1answer
37 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 ...
3
votes
1answer
387 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 ...
5
votes
6answers
667 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 ...
1
vote
1answer
82 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
4answers
2k views

What would sections of a book that are larger than a chapter be called?

I'm writing a technical book, and I want to split my book up into about 3 to 6 very broad sections, each of which would have several chapters in it. Is there a standard name for these broad pieces ...
4
votes
3answers
124 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 ...
7
votes
3answers
504 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 ...
1
vote
2answers
56 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
92 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 ...
2
votes
3answers
128 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 ...
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
84 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 ...
7
votes
5answers
1k 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
1answer
70 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 ...
9
votes
6answers
947 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
1answer
82 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
83 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
358 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 ...
5
votes
3answers
177 views

How to leverage social proof?

How can one use social proof as an argument without sounding like "just because everybody is doing it so should you"?. My problem is trying to demonstrate with social proof that trendy ...
3
votes
3answers
269 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 ...
8
votes
3answers
162 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, ...
8
votes
2answers
336 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 ...
4
votes
3answers
417 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
191 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
90 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 ...
2
votes
3answers
447 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 ...
1
vote
2answers
75 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
117 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 ...
8
votes
3answers
180 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
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 ...
5
votes
2answers
279 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
265 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 ...
5
votes
4answers
548 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
305 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
256 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 ...
1
vote
4answers
1k 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
37 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
212 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
111 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
470 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
282 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 ...