Readmes or massive comments? What's your preference?

[PK8]

I'm making this topic because I'm working on a pause script that will have A LOT of features and several that are going to need some explaining.

I was working on a readme in OpenOffice, came by on this site and read a shout by MicKo which kinda inspired this topic. :P

Would you prefer to read a script which is simply just a huge comment block dedicated to explaining everything in a script or would you prefer an external text/word/open office document instead?

[EJlol]

It really depends on the size, and how much you need to explain for each option. Most of the time I like to see comments in this way:

# comments about option A
option A
# comments about option B
option B

etc.

[MicKo]

I prefer having the comments where I need them. Like EJlol said, basically.

[Yin]

Comments where needed help the user learn scripts themselves. Charlie lee has lots of comments in his script and i know exactly where and how to edit something if I needed it changed. But a big comment block in the beginning is also helpful.

[DerVVulfman]

I have been needing to use both. Of course it depends on the script.

For one-pagers, I tend to put all my instructions and junk at the beginning and for larger ones, I may have just one page dedicated to the instructions.

I had to start doing that when people kept losing the instructions or stopped reading the post itself. Other than massive ones where you just KNOW you'll need a manual, many people just hate additional downloads. Even so, there are so many that still don't download the instructions.

[EJlol]

A good (short) script should be self-explainable, this can be accomplished with using good variable names, not to many options and in case where the user has to add something (hash, array, etc) a few examples.

Ofcourse this doesn't work with very long scripts.

[Kain Nobel]

I perfer comments too, as ReadMe files take up space on my harddrive and I'm a cheapskate with my 300GB of memory lol. Besides that, ReadMe files are easy to loose.

"Oops, I just emtied my Recycle Bin and the project with the instructions was in it... I forgot how the hell to use this thing!"

[EJlol]

...as ReadMe files take up space on my harddrive...

so do comments :P

[Charlie Fleed]

I think that both are needed simply because they usually have different intended readers.
A scripter that wants to modify some script or someone who reads scripts for learning will likely need comments throughout the code, while a "pure user" will benefit from a user guide/readme that focuses on how to use the script instead of how it works.
Finally, but this my personal idea, I don't like to find a big readme in form of an initial wall of comment, mainly because a good readme should present the information in a well structured fashion, including tables, pictures, and so on, and a such thing cannot be done with comments only.

[Asi]

if you go with readme you should save in .txt not everyone has a fancy text editor^-^

-Asi