Readmes or massive comments? What's your preference?

[EJlol]

there are free fancy text editors you can download. Though a .txt is IMO much better than lets say for example a .doc. It takes ages before Word finally opens, while a .txt always open immediatly. Not to mention that a .txt file is much smaller and can be viewed in a browser, so that you don't have to download it.

[PK8]

Yeah, I'd definitely prefer a .txt over a .doc or openoffice's file format any day. :P

[Asi]

there are free fancy text editors you can download. Though a .txt is IMO much better than lets say for example a .doc. It takes ages before Word finally opens, while a .txt always open immediatly. Not to mention that a .txt file is much smaller and can be viewed in a browser, so that you don't have to download it.

I have word just making the point that not everyone does

-Asi

[Charlie Fleed]

Well, since the user shouldn't need to edit it, I guess a pdf would be a good way to go for a readme if you need pictures and stuff. A pdf can be viewed in a browser as well.

[Asi]

Well, since the user shouldn't need to edit it, I guess a pdf would be a good way to go for a readme if you need pictures and stuff. A pdf can be viewed in a browser as well.

yeah .pdf is a good format if you need images how ever I would still recomend having a .txt with as well since pdf needs a reader (adobe) to open whether in browser or on hard disk while .txt can be opened in just about every OS without any additional programs

-Asi

[henasraf]

Why not use .html? Opens in a browser, fast, global, no need for programs we don't use, easy to edit (get a WYSIWYG editor if you don't know HTML?) and has all the formatting you can ask for!

[EJlol]

Well, since the user shouldn't need to edit it, I guess a pdf would be a good way to go for a readme if you need pictures and stuff. A pdf can be viewed in a browser as well.

Please no, I hate pdf's. They are slow to load, and my browsers crashes each time. If you really need to do something with pictures and that kind of stuff HTML would be a much better choice.

[Asi]

I agree HTML is the best *hugs HTML*
^-^

-Asi

[Zeriab]

It depends on the size of the script. (And of course the script itself)
For decently sized scripts I prefer to have the inline documentation intended for other scripters with a topic (or readme) which explain how to use it for the intended audience of the script.

For readme present in the downloadable script demo I'd prefer .txt or .pdf if .txt is not feasible.
I would definitely not prefer .html, especially not if there are images. It's much easier with a single file rather than the numerous files for an html version.
For the topic I utilize BBCode since it's easier since I don't have a web server.

[DerVVulfman]

Eep. I've seen how painful .pdfs are when brought up in a browser. While one of my systems uses a .pdf file, I really expect it to be downloaded, not viewed online. I needed a .pdf for the sucker. Text just wouldn't do, and at times, I need the graphics.

Otherwise, I have the instructions in the script so they can't get lost.