WFSWiki Now Online

Hi Aaron,
It's clear to me that i will *not* use this documentation. It gives the same horrible feeling to me as the builtin L.R. in Rb2005r1: click forward, click forward,click backward,click backward, click forward,click backward, click backward:.... damned where am i now-experience to me. I hate this kind of help-files. I think you know the help-files from Rapid-Q from William, they are simple straight forward, easy to use, easy to understand and i think rather easy to maintain and update, and most of all easy and fast to make if you have the template.
Sorry to say this but this kind of documents degrades IMHO the excelent quality of the product.
Best regards,
Andre

I take it you hate MSDN then as well? That's actually what I modelled the docs from.

Having never used Rapid-Q, I'm not certain what his docs are like. Do you have a link?

Sure i hate MSDN for the same reason, but sometimes there is no other source.
http://www.ansatheus.de/_at_dokserver/2_Programmierung/2_RapidQ/documentation.zip
In these docs you will find the help for the objects in Rapid-Q, e.g. documentation\Appendix A QSTRINGGRID.htm.
You will see it's simple and straight forward. But to be honest i don't like some parts of this docs either. Among others, just this example shows that a rather complex object can be explained in a simple and usefull way.
HTH.
Greetings, Andre

I've had trouble with MSDN mainly because the information is often quite crytic and the search is rather poor (in my limited experience). I think your wiki is just fine - especially given that it has a limited amount of content to cover.

Good work!

~joe

Wow, aside from the fact that the docs are in a language I can't read (German perhaps?), I personally find that sort of documentation to be terrible. I happen to love MSDN when it comes to information because the layout is sensible and the See Also features are worthwhile. Joe is right though, the search *sucks* for it!

The reason I like the way I have WFSWiki laid out is because you can see general information about the entire module, including function parameters and return values. But if you're interested in more detailed information and examples, you can click on the method itself to see the details. You're given enough information to browse an entire class easily, but not so much information that you're left scratching your head.

Did you look in the zip-file? IMO there are only files in english. The website is German indeed.
For me that forward/backward clicking turns the information into loose sand, converting information into data.
But that's my opinion, you are ofcourse entitled to your own opinion.

Your right, it seems that just the index page is in German -- the actual docs themselves are in English (I was really thrown off by the German since I know William's Canadian :-P).

I guess everyone works in different ways. What I'm slightly lost on though is the fact that the Rapid-Q's documentation gives very little depth of information. It's basically just a way to see what the various APIs are -- nothing more detailed than the syntax. How is this different from the class view in the WFSWiki?

I ask because I realize that not everyone works the same way that I do, and I'm happy to find a solution that appeases the most people.

IMO, if there is an explanation there should be a coherent introduction of the full object, then the user can select additional info and not as it is now hopping from a little piece of info to another one and loosing sight on the whole object:
see the leftmousebutton-page, 4 lines of comment and further the info that there are no parameters, no return value.
A whole page with 4 lines of additional info and two N/A 's that all could / should be on the main page IMO.
That's where, as i see it, the additional info turns into data and makes the first page incomplete.

Shelli can't go on Thursday cuz she has to work. But that doesn't mean that the rest of us still can't meet up. It doesn't matter where we go. Pick a place and I'll be there:)

Oh, i would say the userinterface itself is OK. But you could compare good information with a beautiful woman, the packing is mostly in the way :-D

@Andre -- the reason for having a section for each method alone is two-fold. 1) Consistent user experience. It means that the reader knows that no matter what, every method has a link that can take them to more information. 2) Some methods are going to get quite a bit more information in them than 4 lines. For example, explaining the WndProcSubclass interface and WndProcHelpers module is going to have a ton more information than something which is mostly self documenting. Furthermore, I hope to get more examples in there.

But you are right, for some things, the link is extraneous. But my thought is -- if it's that self-documenting, then chances are, people won't click on the link to begin with (since they can already see the parameter and return type information in the class view). Only the ones who truly need a deeper understanding will delve into that last link.

Make sense? Or am I losing people left and right? :-)

Sorry to say but IMO argument 1 isn't valid, keeping that info on the main page is consistant too! This argument is too often used as an excuse for this kind of solutions and not taken in to account the loosing of the overview on the whole picture, which in my opinion is far more important.
However argument 2 is valid, but then there are other (maybe even better) solutions like the kind of help shown in the MS-office suite. The help there consists also of the main information but everywhere you find that little disclosuretriangles that -when clicked on- give supplementary info without changing pages and without click back's and without loosing the main picture out of sight. This doesn't making extra info-pages unneccesary but they are an exception and in the way you organised the info you are making an exception to the rule.
But again, this is just my opinion. I can't speak for others.

Just forgot to mention:
I like oft a printed example of the explanation, if i would have to print this kind of docs, i will and up with a pile of paper, with on each page only a couple of lines wich give only slightly relevant info on the subject. To see an example in optima forma: imagine a printed version of the builtin L.R. in RB 2005 : you will get a pile of tenthousands of pages....what a mess!!

You keep picking examples of what I consider to be unusable docs... ;-) But you bring up a good point about printing the docs, but making a webpage that's printer-friendly has never been my intention. My goal is to make docs that are easy to navigate to get to the information you need, give the right amount of information at each "level" and allow you to get as much or as little information as you need, and quickly.

I think we're going to have to agree to disagree on this one, sorry! I'm just not comfortable with the documentation concept you present mostly because it's the opposite of what I find useable.

Btw, your main complaint is that you have to click back and forward quite often with the docs. I'd suggest getting a web browser that supports tabs (like FireFox) and open the "drilled down" information in its own tab. Then you can Ctrl+Tab around the information quickly and have quick access to as much of it as you'd like, without having a ton of information that clutters up a single page.

I agree we disagree, what is it nice we both live in a free country!

I use Opera and Firefox, both support tabbed-browsing. But if the subject is rather complex i guess my screen will be filled with tabs leaving no room for information ;-) if i would follow your suggestion.