views:

297

answers:

5

I'm hoping to release a web app soon and a key part of that is going to be the documentation that explains how to use it. While I know of many guides on how to learn various languages I know of none that explain how to explain your application.

Can you recommend any?


To be a little more specific about the target audience

They know what the difference between the browsers are and some even program (so I told them to come here) but most are not especially computer literate and don't know how databases work or what a syntax error means.

+1  A: 

For API documentation, I would recommend Sandcastle. It produces MSDN style docs based on your code comments.

SaaS Developer
+1  A: 

A wiki might be the right answer. There are loads of free wiki services out there, or if you have a server, just install one there. Depending on which one you choose, they are pretty easy to work with. Plus it would allow users of the software to contribute to the documentation as well, either in the form of questions, spelling and grammar corrections or even filling in some of the blanks you might miss.

Try A top down approach as well, Start by listing out the main sections you want to document, and progressively fill in all the details. Check out the documentation to applications that you found especially useful, and follow a similar structure.

Jonathan Arkell
+1  A: 

Book List (with brief description) on technical writing:

http://justwriteclick.com/2008/06/17/reading-lists-for-technical-writing/

micahwittman
+1  A: 

use lots of screenshots. Even better make videos of you performing certain tasks in your application. Camtasia is good for making videos on Windows.

As far as the text of your documentation goes... that's a bit more difficult. I would personally create an outline (like an essay outline) focussing on the purpose of your application. That outline can then become your table of contents (with links of course).

Beyond that, I'm afraid it depends a lot on the type of application you have as well as the audience you're writing for.

That doesn't answer a lot, but I do hope it helps.

Kevin
+4  A: 

In many cases, writing documentation about using an app bears a lot of similarity to writing any sort of how-to documentation, so you can use a lot of "standard writing" sorts of resources to assist you with the technical aspects of writing (grammar, structure, etc.).

A key thing you need to do is choose your audience. Are you writing API doc for developers on the system? End user documentation for the folks consuming the system? Administration documentation for the people deploying and maintaining the system? All of the above? It may be that you write a different type of documentation for each of those audiences.

In many languages, you can handle API documentation by documenting the code inline and extracting the documentation later into a central location. For example, C# offers XML documentation that can be rendered with a tool called Sandcastle and there's a tool called RDoc to extract comments from Ruby script and generate nice documentation. I'd recommend using this sort of approach if it's available to you because it's very easy to remember to change the API doc when you change the code if all of it travels around together.

For end users, a very clean presentation with a good organization will be key, so a more static-looking web site, PDF, or DOC file will be in order. You don't want to make the end user work to follow random trains of thought through something like a wiki. (My mom, for example, would give up using the system if all the doc was in a wiki - it's not friendly to non-techies.) Lots of screen shots, lots of guidance, and focus on how-to for common tasks. "How do I modify my user profile?" sorts of things.

For administrators, it'll be similar to end-user documentation, possibly with even more task-based focus for common admin tasks, but here it's okay to get more technical. Admin docs might be OK in a wiki sort of format, but I still might look at a more static web site than something that the community can mark up too much and confuse people with.

For developers, a wiki is great. You can throw your how-to stuff up there, links to the API docs, and let people thrive in a more self-help, deep tech sort of environment. The ability to contribute commentary, in some cases, might even be a key feature - if someone solves a problem or finds a defect, you'll want them to be able to add doc that explains workarounds or easy solutions to common issues. (It'll also help you improve the product from the back-end perspective.)

In all cases, I'd say look at existing doc you've read and like. Try to follow some of the patterns you've seen - what did you like about it? Do that.

All of that said, I can't stress enough the basics of writing. Good grammar, proper punctuation, correct spelling - these things don't sound important, but it definitely has a subconscious effect, if not a conscious one. Try buying a product and reading through the doc. If it's written poorly and has bad grammar and spelling, does it give you a sense of confidence in the product? No, it doesn't have an impact on the actual technical functionality, but it does impact the reader's psychological perspective, and maybe that's enough. On the other hand, reading through nicely written documentations with good illustration and proper grammar spelling... that gives the reader confidence.

Travis Illig
I like your response. It's nicely detailed.
epochwolf
Indeed, I like it too, thank you :)
Teifion