8 Replies - 847 Views - Last Post: 17 April 2009 - 09:26 AM

#1 rmccarter721  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 8
  • View blog
  • Posts: 139
  • Joined: 10-September 07

Documentation

Posted 16 April 2009 - 07:12 AM

How do you write the documentation for your software?

What headings do you use? Do you use a program to help you?

As a beginner to documentation I need help!
Is This A Good Question/Topic? 0
  • +

Replies To: Documentation

#2 jjsaw5  Icon User is offline

  • I must break you
  • member icon

Reputation: 90
  • View blog
  • Posts: 3,060
  • Joined: 04-January 08

Re: Documentation

Posted 16 April 2009 - 07:57 AM

My work has a template that we are supposed to use for documentation. So i kind of lucked out with it :)

But just a couple starter tips I would include screen shots and break down your application or whatever you are documenting as specific and detailed as possible.

Start with basic functionality and progress to more advanced functions.

Document any problems or "hick ups" that the user might incounter. If possible include how to correct/work around the issue.


I would have a cover page with an Index that lays out what the document has included with it. Keep track of the revisions you make and what you added/changed in that revision.
Was This Post Helpful? 0
  • +
  • -

#3 SixOfEleven  Icon User is offline

  • using Caffeine;
  • member icon

Reputation: 945
  • View blog
  • Posts: 6,342
  • Joined: 18-October 08

Re: Documentation

Posted 16 April 2009 - 08:54 AM

Quote

How do you write the documentation for your software?

What headings do you use? Do you use a program to help you?

As a beginner to documentation I need help!



I have done a lot of documentation and I'm trying to develop a freelancing career doing just that!

If you want to build an integrated help system for your programs you should probably use HTML Help Workshop to develop it. You do need to know a little HTML to use it though.

As for a written manual find a word processor that you like, like Word, WordPerfect or OpenOffice.org are all good choices. OpenOffice.org is nice because you can export your document to a PDF. You could also use Adobe Acrobat to create PDFs. Just use what ever you are most comfortable with. Most modern word processors can import the formats of the other word processors.

You should probably try to develop a professional writing style but since you are just starting out just try to make everything clear and consice.

Quote

Start with basic functionality and progress to more advanced functions.

Document any problems or "hick ups" that the user might incounter. If possible include how to correct/work around the issue


These are all very good ideas for getting started. I can't think of a better way to put it.

Another thing that might help you as you go. Add comments to your code. I know it is a pain but it will help you when you start to write your documentation. You can go into your classes and methods to see what they do and the functionality that they add to your program.

Quote

I would have a cover page with an Index that lays out what the document has included with it. Keep track of the revisions you make and what you added/changed in that revision.


Yes, version control is essential to writing good documentation.

Somethings you might want to try to help you develop your writing skills.

Try writing a blog about something you like. Try writing and explaining snippets. When you get good at that try writing tutorials for others.

That is about all I can think of at the moment.

*editted*
For some reason my tags aren't working. :(

This post has been edited by jjsaw5: 17 April 2009 - 04:24 AM

Was This Post Helpful? 0
  • +
  • -

#4 jjsaw5  Icon User is offline

  • I must break you
  • member icon

Reputation: 90
  • View blog
  • Posts: 3,060
  • Joined: 04-January 08

Re: Documentation

Posted 17 April 2009 - 04:26 AM

Quote

*editted*
For some reason my tags aren't working. :(



One of your closing quote tags was misspelled. I corrected it and its working now.
Was This Post Helpful? 0
  • +
  • -

#5 rmccarter721  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 8
  • View blog
  • Posts: 139
  • Joined: 10-September 07

Re: Documentation

Posted 17 April 2009 - 05:22 AM

Would anyone be able to post a sorta template? As i know that would help people like me. Means others can develop it to make their custom template then
Was This Post Helpful? 0
  • +
  • -

#6 SixOfEleven  Icon User is offline

  • using Caffeine;
  • member icon

Reputation: 945
  • View blog
  • Posts: 6,342
  • Joined: 18-October 08

Re: Documentation

Posted 17 April 2009 - 06:56 AM

View Postjjsaw5, on 17 Apr, 2009 - 03:26 AM, said:

Quote

*editted*
For some reason my tags aren't working. :(



One of your closing quote tags was misspelled. I corrected it and its working now.


Thanks. :)
Was This Post Helpful? 0
  • +
  • -

#7 SixOfEleven  Icon User is offline

  • using Caffeine;
  • member icon

Reputation: 945
  • View blog
  • Posts: 6,342
  • Joined: 18-October 08

Re: Documentation

Posted 17 April 2009 - 07:07 AM

View PostFurnfield, on 17 Apr, 2009 - 04:22 AM, said:

Would anyone be able to post a sorta template? As i know that would help people like me. Means others can develop it to make their custom template then


I guess you could try something like this:

Table of Contents

Introduction
Purpose
Features
Use
Limitations/Problems/Work Arounds

for each window
Introduction
Features
Use
Menus
Menu Items
Controls
Limitations/Problems/Work arounds
Dialogs
Features
Use
Menus
Menu Items
Controls
Limitations/Problems/Work around

Index

I think that would be a good general layout for a document
Was This Post Helpful? 0
  • +
  • -

#8 rmccarter721  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 8
  • View blog
  • Posts: 139
  • Joined: 10-September 07

Re: Documentation

Posted 17 April 2009 - 08:23 AM

Thanks.

a few links i have found

http://www.mit.edu/~...umentation.html
http://www.winnersht...ingSoftware.asp
Was This Post Helpful? 0
  • +
  • -

#9 Tom9729  Icon User is offline

  • Segmentation fault
  • member icon

Reputation: 180
  • View blog
  • Posts: 2,641
  • Joined: 30-December 07

Re: Documentation

Posted 17 April 2009 - 09:26 AM

I use Doxygen.

It generates HTML documentation from your code comments.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1