[twsocket] ICS documentation
Hi ! As you probably know, we have a Wiki for ICS documentation: http://wiki.overbyte.be A wiki is a collaborative tool. We already have a few authors writing articles. Actually not that much ! If you have some spare time, please use it to write some article in the wiki. If each ICS user write only a single page, we will have tens of thousands pages ! No need to know everything. It is enough if you know ONE thing. Just write a page and you'll enter the hall of fames :-) To collaborate, just login onto the wiki and email me the usercode you selected. I will give you write permission. Thanks a lot. -- francois.pie...@overbyte.be The author of the freeware multi-tier middleware MidWare The author of the freeware Internet Component Suite (ICS) http://www.overbyte.be -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
Re: [twsocket] ICS documentation
> My very personal reason is that I don't like APIs documented in a > Wiki as they are incomplete most of the time (e.g. lack of type > information for properties and events) and the required effort to > keep this in sync with the code is very high. I agree, and I've said the same thing to Francois several times over the years. Probably 50% of the documentation value is accurate properties, methods and events which can be created automatically from the source code. Adding descriptive documentation in the source for new changes should not take a developer very long, I usually document my changes in various places in the source so people understand what I've done and why. But adding the initial documentation to the source is very tedious, and even harder for non-English speakers. I've used F1Help from Janco Tanis for 10 years to document my RAS component, he kindly sent me the Delphi source so I could fix a couple of bugs when he stopped supporting it, but it would probably need another update to handle the vast number of ICS units. It originally took me about a month to document the four main units in the RAS component, which is the main reason it became commercial, so I got paid for my time. Angus -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
Re: [twsocket] ICS documentation
Markus Humm wrote: > What is so hard in documenting just a single property or work on those > property overview pages which aren't complete yet? Copying the table of > a already started property list to a not yet started one and modifying > it so that the correct properties are listed is not hard. My very personal reason is that I don't like APIs documented in a Wiki as they are incomplete most of the time (e.g. lack of type information for properties and events) and the required effort to keep this in sync with the code is very high. As I am already browsing the code in 95% of the lookup cases I tend to document my personal code in-line instead of separated from the code and use a tool to output fancy HTML directly from the sources (http://www.naturaldocs.org). Writing tutorials and how-tos is a different thing. In my opinion a Wiki makes sense here. Regards, Tobias -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
Re: [twsocket] ICS documentation
On Mar 01, 2010, at 14:36, Markus Humm wrote: > Sorry if I sound a bit harsh, but this topic comes up now and then but I > don't see any progress in form of other volunteers working in the wiki > (except some of the main developpers of ICS, but this is not enough and > I don't blame them - they need to keep ICS current). Markus, Although I understand your frustration, please consider the many people that have actually contributed in many other ways to the ICS project. Either by providing code, testing, or offering support for free. Over the course of a decade, volunteers have created complete sets of documentation files, in various formats, including Windows Help, HTML, etc. All these projects have eventually been abandoned due to the constant dedication and effort required to maintain them, but they have been there. The Wiki is just the latest one. Although I agree that a comprehensive documentation effort would be of great value to the ICS community, keep in mind that what has traditionally differentiated ICS from say, Indy, is the community itself. ICS support--this mailing list in particular--has been unparalleled. You are welcomed to contribute all you can to the ICS Wiki, and so is every other member of this mailing list. Any little time is appreciated by all of us, but ultimately we recognize that it is a volunteer effort. Sincerely, dZ. -- DZ-Jay [TeamICS] http://www.overbyte.be/eng/overbyte/teamics.html -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
[twsocket] ICS documentation
Hello, I can only subscribe what Francois said. Another annoying this is, that many people already promised to help a bit in the wiki but didn't do it up to now. The list of registered Wiki users is already long now, but most of those didn't yet write a single page of it. What is so hard in documenting just a single property or work on those property overview pages which aren't complete yet? Copying the table of a already started property list to a not yet started one and modifying it so that the correct properties are listed is not hard. I've done it already in the ICS wiki. Don't tell me you have not even 10 min time to do something like this (ni needn't be complete just a start which has sufficient quality so it can be extended) given the fact that you get several 1,000 lines of quailty source code for free when downloading ICS. ICS is simply a open source project and thus needs your help. Another option to improve help/documentation is to pay Francois well enough so he can spend some days on it. But I don't see that being done either. It's cheap to get ICS for free but then also request documentation being done for free from others as well. Sorry if I sound a bit harsh, but this topic comes up now and then but I don't see any progress in form of other volunteers working in the wiki (except some of the main developpers of ICS, but this is not enough and I don't blame them - they need to keep ICS current). Greetings Markus -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
[twsocket] ICS documentation
I always want to say a problem: I sincerely hope that the ICS team can write a complete help document. ICS is an outstanding component suit, and demo program is also very rich. But over the years, ICS has not been a complete Help documentation, which is really a regrettable thing, and which is the biggest obstacle for extensive used of ICS. I agree with you that the lack of a good documentation is an obstacle for ICS. But I don't agree with you that it is ICS Team which must write it ! Actually I've setup a wiki for documenting ICS (http://wiki.overbyte.be). Wiki is a collaborative tool and I expect every ICS user to write a part of the documentation. Many user say "I don't know enough ICS to write the documentation". This is really wrong. Any good Delphi developper is able to write basic documentation by reading the source code. More experienced user will make better descriptions. Anyone willing to write the documentation is welcome. Just ask me to get write permission. There are 800 subscribers in this mailing list. If every one write even a single page, then we have our documentation ! -- francois.pie...@overbyte.be The author of the freeware multi-tier middleware MidWare The author of the freeware Internet Component Suite (ICS) http://www.overbyte.be -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
[twsocket] ICS documentation: a wiki has been setup
I've setup a wiki for ICS documentation. A few guys have helped to set it up: Arno, DZ, Guillaume, Wilfried, and some others. The system is working. We defined a layout and entered the component list, some component, the start of a FAQ and so on. Now we need writers to enter the actual data into the wiki. There is work for everybody: no need to know every details about ICS. If you can read source code, you can help a lot just by entering the properties, events and methods lists with a short description which is most of the time already in the source code. Other people with more knowledges can write extensive documentation about specific components they know better. Wiki is a collaboration tool. Everyone can give his 2 cents participation. Everybody willing to participate can explain (here in the list or by direct mail to me) what he can do. I will give write permission to the wiki. The wiki is available to everyone at http://wiki.overbyte.be There is a dedicated mailing list to discuss wiki content. Every writer will be invited of course. -- Contribute to the SSL Effort. Visit http://www.overbyte.be/eng/ssl.html -- [EMAIL PROTECTED] Author of ICS (Internet Component Suite, freeware) Author of MidWare (Multi-tier framework, freeware) http://www.overbyte.be -- To unsubscribe or change your settings for TWSocket mailing list please goto http://www.elists.org/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
