Hey Abob and other Modder types!
No, my intent here wasn't to 'have a go at modders', as you indicated it wasnt. My thinking when I posted this thread was simply 'when I read the first post of the threads of a few mods, they aren't really all that descriptive'. Oh, you'd be surprised, a lot of Mods do not include readmes, and the ones that do usually say 'here is how you install my mod', not so much 'this is what my mod does, in more detail'.
Certainly, in the interest of not cluttering up the regularly updated list of mods thread, I have chosen to keep things short (4 lines or less usually), and given the sheer size of that list now, it makes sense. But as for the modding thread itself, well that first post is the first thing that a person is going to see when considering your mod, so the more comfortable you can make someone feel with your mod at that point, well I just think that's a goal to keep in mind.
Certainly, you don't want to give away all of the cool little secrets you may have included in your mod (example: an entire structure for a quest, no sense telling someone exactly what is going to happen when in that quest, otherwise it isn't an adventure the first time 'cuz you know the outcome already). But, as I noted, if your mod has several variations that can be implemented, a more detailed readme explaining what your various files will do is perhaps not a bad idea.
Sure, some people will just drop your mod into the mod folder and hope it works on the first try, and for'simple modifications mods', i.e. the ones that essentially change just one thing, that's probably fine: I'll use Monuments XP as an example here, it modifies Monuments, Guardian Statues, and Guardian Idols, adding XP bonuses to them. Pretty straightforward mod, one file, plug and play.
It's the more involved mods with multiple files that change a few things, well consider this. I've seen the comment a few times that 'this mod looks like it changes too much, and I'm not sure what it does'. The more involved your mod is, by definition the more things you are changing, and some people like the 'vanilla' E:LH experience and don't want to deviate too far from it, due to game balance issues or simple preference. Essentially, they 'trust' what was done in the game already.
So, if your mod looks like it completely changes the game (it may not, but based on the number of files you have, it seems like it), well if you haven't made a good presentation at the front end (when people first see your mod), to let them more carefully consider what your mod does and if it is for them, well they simply take a pass and don't give your mod a whirl. Which is a shame, because a lot of you have done some really cool mods, and put a lot of work into them. But by not taking a little more time after you have wrapped things up to 'pitch' your mod, well you end up selling your mod just a little bit short. So for those that WANT a little more info, they may just move on when the info isn't there.
Also, if you aren't showing off exactly what your mod is doing, well how are people supposed to know that it does this cool thing, this other cool thing, this umpteenth cool thing if you haven't taken the time to tell them? THIS is I guess the point I was trying to express. The more involved your mod gets, well if you have said 'and an assortment of other changes' in your mod thread, well that statement can make the uninitiated and/or more conservative players a little uncomfortable about your mod.
Also, and I'll admit it's a personal experience, sometimes when you see a mod thread, you download the file immediately, but aren't intending to try it out until later. In some cases, MONTHS will pass before you decide to try out that mod. So you see this .zipped modfile in your 'to try out later' folder, open it up, and there isn't anything in that folder that explains what the mod does (Sure, the .xml files could tell you exactly what is being done, but a lot of people won't comprehend the various gamemodifier, etc. .xml tags used in E:LH, so if you don't 'speak' .xml, it's a foreign language). So you spend some time trying to 1) remember where you found the mod (in some cases, the mod may have not come from this forum), where the thread for it is, and then spend time reading a bunch of posts and replies to try to figure out what the mod was about. Yes, this isn't a common occurence, but this is where a more detailed readme becomes invaluable and can save a lot of time.
OR, you tried a mod a while back, uninstalled it and forgot about it (but still have the .zip file in your download folder), and then are looking at the folder trying to figure out what the mod actually was... there are a LOT of mods for E:LH at this point, so if you download a lot of them, well when you are staring at 6 dozen+ zipfiles when you open your E:LH 'mods you've downloaded' folder...
Another thing that can be done is you could 'comment out' a statement at the beginning of your .xml briefly explaining what the .xml file is changing/adding, and any interdependencies that file may have (a gfx file or whatever), but a number of people aren't going to dig into your .xml file looking for info, and if you have say a dozen .xml files in three or four folders... that just isn't practical. The 'commented out brief synopsys' thing is often done more as a courtesy to other modders/coders, but certainly some others might see it there. A detailed readme would be so much faster though...
I hope this better explains my thoughts on this, and my reasoning for posting the suggestion r.e. better documentation. Some modders are pretty good with this, but not all of us think about the importance of good documentation while we are coding and releasing mods.