There have been a couple of other questions about explaining technical things to non-technical people, but I am specifically wondering if anyone has any tips for explaining technical problems to business oriented clients. For example, suppose the client asks for a specific feature, with certain requirements. However, the technical limi...
I read Richard P. Gabriel's book "Patterns of Software" (pdf) which contains an essay called "Writing Broadside" in which he contends that programmers should develop their ability to write clearly. I have found that his suggestions have definitely improved my ability to write tech. spec's and design documents. One of his suggestions is ...
I have a blog that I would like to increase traffic on. I've read lots of technical blogs, but it's a lot different writing a blog versus reading a blog. There seems to be several ways to write a post. General article: I like this tool. This is how I do it. Specific technical issue: Programming solutions. I do get some traffic, but...
I've noticed (is it just me?), that the really, really good programmers seem to be good at writing. Like their code flows, so does their written language. To me, I suppose that makes sense: programming is writing programming languages. One writes code. Different code is written in different languages. In your opinion, subjectively, doe...
When writing a technical design document of a yet non-existent application/system, what aspects would be most helpful for the developers - assuming that the person writing the document is not involved in the actual development? There are some obvious things, and standard structures, of course, like system architecture interfaces (exter...
I am interested in technology, what steps should I take to become a technical writer? ...
Writing documentation is part of programming, and writing well is part of what makes the documentation useful. So, what are some hints or guidelines for good writing in the technical realm? What are some resources (on-line or on dead trees) which might help me to improve my documentation? ...
Lately the company hired a technical analyst for the dev team. For all new projects it's his tasks to analyse the clients demands and come up with an analysis design that can be used as a starting base for actual development. Now apparently this techincal design will contain some sort of class diagram that should be used as a guide by t...
I have written a book for Packt publishing because they asked me too. Having gone through a year long experience with them I found that there were many pros and cons to having written for them - a fairly new publisher (upstart built from the staff that fell out of the Wrox buy out). Question: Having enjoyed the writing process quite a ...
I was wondering if any SO members have had the opportunity to self publish a programming related book. Do you have any advice regarding the process? I don't have any problem maintaining the structure of my book, table of contents, and actually pumping out the chapters. But what does one do for technical reviews, editing, proofing, etc...
I have to write up a technical document in Framemaker that explains various programming source-code. So my document consists of a bunch of text, followed by a bunch of source code (Java, XML) and then followed by more text, etc. This question is not about whether I should or should not use Framemaker - that is the software I have to ...
Many applications are let down by the quality of the 'writing' in their user interfaces: typically, poor spelling, grammar, inconsistent tone, and worse yet, "humour" are the usual offenders. Are there good resources that can help developers to write UI messages that give a professional and positive impression to your customers, even wh...
I need to find a technical reviewer for a programming document. I have looked on Craigslist and various freelancers' websites (RentACoder, Odesk, Elance, etc) but it's difficult to determine who is qualified to act as a reviewer. The last thing I need is to have the document reviewed by someone who either doesn't know what they are ta...
I need advice from people who might understand where I'm coming from. I'm the lead engineer on a software product. The company I'm working for recently expressed serious interest in having me blog about it (much to my dread). They even had someone set me up a blog. I have Asperger's disorder. I'm really good at taking complex softwar...
Following what started here . http://stackoverflow.com/questions/141769/what-is-the-best-tool-for-creating-user-guides-with-screenshots-on-windows i need to create a user guide and quickstart for a rails app i will deliver in just a couple of days, need something quick, good, and if possibly free. of course leopard and snow leopard abl...
Problem: I have to write a review discussing the technical aspects of two competing software system (Document management systems). I have to review scalability, availability, maintainability, usability, extensibility, cost, and other relevant aspects. Question: Is there a template or preferred method you have for writing this kind of do...
Prospective clients are asking for production level examples of my work. I've been stuck in Research and Development mode for the past couple years, and don't have anything that I can think of to show them. Suggestions? ENetArch ...
Hi All, I am looking for a decent tech spec documentation template for a MOSS implementation. If anyone can share any existing document template then it would really help me. Thanks Bhaskar ...
I found that IMAPv4 has a shortcoming: It forces users to download whole body (text/html + attachments). How to write and propose a RFC to address the issue? Please kindly share if you had experience of previously writing technical documents, proposals, especially RFCs. Thank you in advance. ...
I am currently writing a formal research report, and I'll be including code with this report. Question: Is there an accepted way of displaying code in research reports? I'm thinking both in terms of font, spacing, et cetera, and whether the code should be displayed inside the document, or in an appendix. The code will be JavaScript and...