Posts tagged technical-writing
I have been hired as a Technical Writer at a firm who needed multiple types of writers: A few people were hired to write content for the average website reader interested in our product, such as a...
Our documentation set includes some diagrams where text is integral and can't be handled in callouts, like flowcharts and entity relationship diagrams. Our documentation is translated, so these di...
The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?
I'm not well versed in technical writing. I'm probably not going to be in a position to give anyone feedback for some time, but I would like to know how to approach it when I get there. I would als...
In technical translation (e.g. of manuals), the quality of the source text often is not very high. This concerns not only the language used, but also the structure of the whole document. Should te...
I have a question on linkers and connectors. I'm from Spain, so I learnt English at school and all my English teachers have told me throughout secondary school that we always have to use linkers t...
How can I properly cite an Oracle's documentation of the usage of certain APIs? For instance HashMap - Oracle Documentation I need to cite/reference this in my research paper, what is the best w...
I have a highly flexible software product consisting of a series of loosely coupled microservices. Each component is effective at a single job, but may be dependent on inputs from other services. I...
I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly beneficial. My question is not how to add d...
In a technical tutorial it is helpful for a user to be able to check their progress often. Veryfing that the steps have produced a result is good because the user: has a feeling of progress can c...
I have no degree and I cannot afford to have one, however, I would really love to get into technical writing because I love writing and I am interested in web and software development. Right now, I...
I use Latex for writing articles/papers/longer documents. Most of these documents are scientific in nature, and therefore it is often useful to add an index of the most important terms at the end o...
Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you capit...
I am writing a corporate guidelines manual. The manual itself is made in InDesign, and contains sample documents in it that show employees how to correctly write/format despatches. These document...
What are the usual typographical conventions to set off text from the UI in a user manual? For example, how should I style the text of the label on a button in: Press the Submit button. Or...
My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions (for variables, admonitions, snippets, and so o...
We use doxygen to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and...
As a software developer, I often find myself writing my own technical documentation and user guides. How much detail should be put into this documentation? When is it too much detail? EDIT I'm...
My documentation team supports a massive software product, over 30 modules. These modules are individually licensed, so one customer might pay for all the modules where another might only pay to us...
We use a BNF style to convey syntax for SQL statements. For a (fictitious) example: CREATE PARSER [schema.]function [WITH [LANGUAGE='language'] [, MODE='[FENCED | UNFENCED]' [, STUF...
I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google). The doc set has a glossary, which pre...
I'm writing a guide to give step-by-step instructions to complete some tasks on the computer. At some points, I need to indicate pressing keys on the keyboard; how may I format the letter/symbol to...
I want to make an announcement to my users at my website about a new feature launch. However, in its first phase, this new feature has limited access - it will be supporting only one city for now, ...
I have the following sentence, NAME is a community that helps each other code better by rating each other's efforts and helps managers pair with other fellow developers I was suggested by ...
When writing a technical report, is it necessary to explain what is written in upcoming chapters? For example in my introduction chapter, I may have a sub-chapter called "Forthcoming chapters" whi...
In technical writing, I have a tic of writing in pairs. Some examples from a recent piece: "When you speak, be sure to be clear and concise." "Face to face conversation is personal and private." ...
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 lon...
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...
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 s...
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 ...
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 l...
In many companies I've seen it that more than 1 person are writing at the same documentation (be it user manual or technical documentation) for a computer application. What I have seen in usage wa...
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 ...
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 a...
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...
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. ...
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 t...
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 rathe...
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 peo...
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 fo...
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 w...
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...
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 referencin...
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 present...
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 ...
What is good/preferred way of presenting directory trees in programming books? My main criteria are following: It should be readable and intuitive It shouldn't take too much page space It shou...
Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader. In technical writing the later is very typical (at least for me), one can ten...
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 ...
I've looked at some of the largest outsourcing sites. These have huge amounts of software developers, and huge amounts of casual writers. I'm having enormous difficulty finding authors that would...
A Japanese company has offered me a gig helping translate an Android1 business application + documentation into English. Their staff will do a rough translation, and I will polish it into something...
