| Author |
 Topic  |
|
dcwebman
Junior Member
USA
105 Posts |
 Posted - 05 April 2001 : 14:37:52
|
I have convinced my group to use the Snitz forums. So what's the first question they ask me. Where's the doc? I would be eager to take ANYTHING that anybody has that resembles some documentation. If you have anything, please send it to me at dcwebman@hotmail.com.
Thanks!
-----------
Jeff< |
|
|
joewc1
Starting Member
3 Posts |
|
|
work mule
Senior Member
USA
1358 Posts |
Posted - 28 April 2001 : 16:46:53
|
LOL! 
Snowball with something. Point them to the FAQ page. If that doesn't work, tell them that like many products, "documentation" can be found online (here at the forums). The forums can be your documentation - due to the quick development cycle and evolution of the product, formal documentation would become quickly outdated. 
Good luck!
< |
 |
|
|
work mule
Senior Member
USA
1358 Posts |
Posted - 28 April 2001 : 17:32:19
|
Seriously, forgot about the obvious. The readme.txt file that's included in the Snitz download also contains a lot of information that's needed to get the forum installed (at least the recent beta did). Seriously between that and the forum, that should be all the documentation you'd need. That's a lot more than you'll find in some programs. I don't think that you need a big formal book of fluff to have a great program.
< |
|
|
|
mrWize
deleted
119 Posts |
Posted - 21 May 2001 : 17:14:50
|
But, the documentation should even cover the code itself so other can develope their on MODs, tune the forum up some bit. As it is now, the code itself looks real *****y to me, not selfexplained, variables used in one function are taken outside the function not explained were it came from, thats not good coding standard.
To write this document .. woah .. dont think anyone can ... is a HUGH full time job to do as it is today.
Hope someone KNOW what every variable is for etc ...
cya,
mrWize
< |
|
|
|
RichardKinser
Snitz Forums Admin
USA
16655 Posts |
Posted - 21 May 2001 : 17:47:08
|
| You are entitled to your opinion. I'm not sure why you have felt the need to come here and insult and criticize today. I'm sure you have your reasons, whatever they may be.< |
|
|
|
Doug G
Support Moderator
USA
6493 Posts |
Posted - 21 May 2001 : 21:06:15
|
quote:
To write this document .. woah .. dont think anyone can ... is a HUGH full time job to do as it is today.
Hugh Who? :)
======
Doug G
======< |
|
|
|
mrWize
deleted
119 Posts |
Posted - 22 May 2001 : 15:13:32
|
BIG job ... sorry for my bad english =(
and I got pissed off .. You know why ..
so ... we can take this discussion inside the moderator forum if You like .... but, its still my opinion ... and Hope I´m entitled to have that opinion ...
cya,
PatrikB
< |
|
|
|
gor
Retired Admin
Netherlands
5511 Posts |
Posted - 22 May 2001 : 15:47:14
|
Everyone is entitled to their opinion around here as long as the discussion about what could be better is constructive and not just pointing out what is wrong.
When you work many hours coding this forum you tend to get a bit angry when someone just starts stating that it all isn't good what we do (about as angry as you got when you thought your post was deleted).
So, although I think that it is good to have people like you around that keep us sharp, please try to keep it friendly and non-sarcastic.
p.s. like you, English isn't my native language, I know it sometimes is hard and difficult to stranslate some feelings into English. But that means people like us need to read over our posts more than once before hitting the post button.
A smilie sometimes helps to explain if your are very serious about what you say or not.
Pierre
Join the Snitz WebRing< |
|
|
|
mfindlay
Junior Member
USA
144 Posts |
Posted - 28 May 2001 : 17:13:05
|
I agree that if I was to suggest to my company that we commit to the time and effort it would take to implement this messaging system, they would want to have something more robust than a readme.txt file to review.
Don't get me wrong, I have only just begun to use Snitz at home as a sort of test, and I think it is a great great product, but one impression I have developed is that documentation is seen as practically unnecessary, or not worth the developer's time etc.
I can't imagine any top notch commercial program being offered that only provides a readme.txt file. Even though they may be bug free and easy to use, they still provide a complete working on document on every detail of installation, de-installation, administering the product, things to look out for when running, other issues etc. Can you imaging buying Windows and getting only a readme.txt file on the CD?
In my opinion, the most sophisticated help systems (I will use Dreamweaver as an example) provide their help in the form of a link to a help file on their website. To me this is a fantastic help system and a clear example of taking advantage of the technology offered.
It takes no more (maybe a little more) time to write a document in html than in a .txt file, but it is so much more readable, offers all the benefits of html formatting like hyperlinks and jumps etc. And, the most powerful benefit of all, when Dreamweaver updates their htm help files on their site, ALL Dreamweaver users automatically see the most up-to-minute docs, including FAQs, new info, new links, etc. And Dreanweaver then does not have to worry about the cost of redistributing docs, and are assured users have the most current info. An absolutely perfect use of the technolgy!
My ideal world: Snitz would promote the use of htm documentation in both their own forum product and in MODs done by other developers.
I recently created such a template (based on the readme.txt requirements posted by Snitz) that can be viewed at http://www.sagecomputerservices.com/forum/docs/mod_documentation.htm.
I then took Davio's POLL MOD readme.txt file and converted it using the template (took me about 5 minutes). Davio was impressed by it. Let me know what you think. You can view the POLL MOD htm document at http://www.sagecomputerservices.com/forum/docs/snitz_poll_documentation.htm
Maybe it's just the fact that I am the one offering this suggestion (I hope I'm being objective) but I can't imagine how anyone would not consider the htm approach (with the MOD developer maintaining the htm file on their site for users to visit as well as including it in their zipfile) to be a quantum leap forward in this effort. Especially with the template already available for download.
As long as I'm being long-winded , I can tell you from first hand experience in attempting to install many many different mods in the last week (I'm a good subject since I'm coming into all this new) that the documentation in the many of the .txt files is horrendous! It's as if the MOD developer wrote it while running out of a burning house. Sometimes it's not a big deal, the mod is a no-brainer, but there aren't too many of those. Most are rather complex, and made even more so for a newcomer like me. In looking through the various topic areas in the MOD support forums there are waaaay too many messages that are just repeated over and over with the same problems and the same responses.
When a MOD developer answers one of these posts, if he/she were instead to then add the problem and solution to the FAQ section in their htm page and repost the file to the download area, any new users would have that FAQ in their help and would not have to navigate through what for some MODS are some VERY long topic threads etc.
Well I'm getting tendonitis now so I guess I'll stop for now. I hope I didn't offend anyone. It is not my intention. I really enjoy the Snitz product and I certainly enjoy the MODs. I'm just trying to make life easier for everyone (myself included if the MOD devs adopt this) in the future.
Take care.
< |
|
|
|
RichardKinser
Snitz Forums Admin
USA
16655 Posts |
Posted - 28 May 2001 : 18:24:51
|
You forget that this is not a Commercial Product. Developers of Commercial Products spend alot of money for Documentation to be written. As you can see there was a drive at one time to get documentation written, but it fizzled out. It's a time consuming process, that there really isn't any need for.
As Mike has stated before, this project was started as a way to learn ASP. What better way to learn than to study the code and figure out what everything does. If it's spelled out for you, how are you going to learn?
You have to realize that the instructions for installing a MOD is always done last. After the coding and testing have been done, the last thing most people want to do is sit down and write out long drawn out documentation.
About the forum itself. There is really only 2 lines of code that need to be modified to get this forum up and running. The readme.txt file sufficiently explains these 2 lines of code. Any other questions/situations that arise can be addressed in the Support forum, in the form of a question. The forum itself can be considered one big FAQ, if everyone were to do a search before posting a question. But, we still try to answer each and every question posted.< |
|
|
|
RichardKinser
Snitz Forums Admin
USA
16655 Posts |
Posted - 28 May 2001 : 18:38:25
|
quote:
As long as I'm being long-winded , I can tell you from first hand experience in attempting to install many many different mods in the last week (I'm a good subject since I'm coming into all this new) that the documentation in the many of the .txt files is horrendous!
I do take offense to this. None of the people who write MODs have to release and support their code at all. To call anything that they do "horrendous" is uncalled for. We should feel lucky that so many people want to contribute to this project. I am not about to insult anyone, even if their instructions might be hard to follow.< |
|
|
|
mrWize
deleted
119 Posts |
Posted - 28 May 2001 : 19:24:13
|
quote:
It's a time consuming process, that there really isn't any need for
Just think in debugging .... so, so much easier with a full documentation. That´s a reason big enough to do documentation.
cya,
mrWize
< |
|
|
|
Ribkick
Junior Member
USA
296 Posts |
Posted - 28 May 2001 : 21:18:17
|
To address this issue from a new user of Snitz and a new person to code in general, I too took offense to the tone of the posts here. I have been met with nothing but friendly, punctual responses to my various questions regarding Mods.
I too looked for documentation when I first started here, found none other than the readme and accepted that. I have seen the same questions asked over and over and in some cases been able to answer some of the members questions from my own, rather short experiences here. That I consider is giving back to what is offered here.
Richard has a very good point in that this is not a commercial product. He and many others work very hard to provide a good, sound product and mods with very little thanks from the members. They should receive a vote of thanks and gratitude; not criticism.
Spend a little time here, learn the Snitz way, it's people, and enjoy the trip; not the destination.
If you're looking for a forum for your business, perhaps a capital investment in a commercial product would suit you better.
< |
|
|
|
big9erfan
Average Member
540 Posts |
Posted - 29 May 2001 : 12:58:02
|
I just would like to throw my 2 cents in here being a somewhat new member to the Snitz forums and REALLY new member to ASP coding.
When I first started looking at the forum code I was near scared off from ASP coding all together. There were very little commenting and such, to understand what was going on where and why. After spending some time in the snitz code base though, it has become a non issue. Sure I can't track down a problem as fast as Richard, Huwr, gor ( or the many others that can probably recite this code line by line in their sleep ) but this has taught me A LOT on the subject of ASP coding. Sure I have a lot more to learn and there are MANY aspects of the Snitz code base I am still fuzzy on, but that only drives me to spend more time in it to learn it. As per documentation on each variable, function and database call I think that is FAR from necessary.
Real world example: 2 years ago I took an intership at a company that develops a software product. There are about 10 developers here, but there is NO documentation for the code. There are some scattered comments here and there, and as more of the code is re-written more and more comments are put in so we remember what the hell is going on, but other than that there is NO code documentation. We are currently developing an API to let customers access bits and pieces of our base code, and that is being documented fairly well. The only piece of code I could see in the Snitz base that would be analgous to an API would be inc_functions, but even then I don't see documenting that as a necessary task.
The only real docs that need to be expanded upon are the FAQs to include for Admins and Mods how to do what they need to do ( i.e. create new forums, make them private, delete members, delete posts, edit posts, etc ). Even that though is difficult to make general as people have their own terms in which they dub a post should be edited and such. I believe Huwr was/is working on a FAQ template of sorts that stores info in the db and pulls as necessary to a predetermined page, and that is probably the best customization of docs that can go around.
I am very grateful to all those that put in the 1000s of hours to make this the great product that it is, and all those that put in additional hours making mods to make this ever evolving prodcut even better.
http://www.ugfl.net/forums< |
|
|
|
work mule
Senior Member
USA
1358 Posts |
Posted - 29 May 2001 : 13:58:57
|
 
Hmm...probably a good thing I didn't read this before posting my reply over in this topic.
http://forum.snitz.com/forum/link.asp?TOPIC_ID=10243
I'll stick to that as my reply in regards to documentation.
But I need to add something...
When I first downloaded the Snitz code and started to work with it, I had about one year of ASP/VBScript programming experience. Not even a full year because I've done a lot of programming in other languages in that same time frame. I thought I had a fairly good handle on it, but when I started to poke around in the Snitz code...WHOA!! There was a lot of code and it was intimidating!!
Anyways, it challenged some perceptions that I had about ASP and how some things should be done. The Snitz Forum code taught me a lot about ASP and interacting with DB's that on my own, I would have probably taken years to try.
Looking back at my first attempt at modifying the code, it was terrible, I broke so many things! There was so much code that I modified and had no idea what it did. But having done this, I learned so much about the forum code and ASP, that I'm glad that I did it. Even with documentation, you can't appreciate what's being done and why until you try it (and break it). With that knowledge, the next attempt at modifying the code was great! I still break things, but now it's generally on purpose.
"Do not go where the path may lead, go instead where there is no path and leave a trail."
-Ralph Waldo Emerson< |
|
|
|
Topic |
|
|
|
Forum Locked
