[crossfire] CFDialog Documentation (was Re: Vote: Next major project)

[Yann Chachkoff]

Le Tuesday 21 August 2007 10:42:03 Kevin R. Bulgrien, vous avez écrit :
> > > L) NPC chat right now really isn't very good.
> >
> > *sigh*
> >
> > From the header of maps/python/CFDialog.py:
>
> <snip>
>
> > See also http://wiki.metalforge.net/doku.php/cfdialog
> >
> > It is always refreshing to see how one's work is appreciated :).
>
> From the documentation indicated, I would not easily know how to make
> a map that uses this since I do not know squat about using python
> scripts in maps.
>
Documentation reference:
- "How do I hook a script to an object", from server/doc/Developers/python
- Same title, from http://wiki.metalforge.net/doku.php/cfpython

Of course the CFDialog does not explain how to write Python scripts, since 
this is already documented elsewhere. And no, the CFDialog document doesn't 
explain what an NPC is, or why they are answering using speech; for what 
matters, all this is supposed known from the rest of the documentation.

> The code documentation and wiki documentation is too 
> light, and could show an example of an NPC definition that uses the
> script example.  
>
See above.
For practical examples of NPCs using scripts to manage "say" events, see for 
example maps/scorn/shops/IPO_scorn. Various scripted map examples have been 
in existence since 2001 in the maps.

> It would be nice not to have to go digging through 
> other documents to find out how to do python scripting in general
> just to get started.  
>
There is no "digging" needed. If you had done your homework, you'd have found 
that it is clearly explained in a single document, which can hardly get a 
more explicit name ("doc/Developers/python" and "cfpython" on the Wiki; it is 
also the first entry found when searching for "python" on the Wiki search 
engine.).

Now, if typing "python" in the Wiki search textbox is "digging through 
documents", then maybe we should just trash the whole content of the doc/ 
directory and from the wiki, since it is probably too difficult to find 
anything useful in it.

> If that were the case, I'd probably make use of 
> what I did know (even if that is only a lazy slob's excuse).  It would
> be better to show a complete example, and reference the docs that
> discuss python scripting as it relates to map editing as a way
> of encouraging the reader to broaden their understanding of the
> available tool set.
>
The example given in the wiki is a *complete* script. It is expected that the 
reader will be clever enough to read the related Python page (which is *also* 
linked from the CFDialog wiki page) if he/she has trouble for hooking 
scripts.

There is a complete example, there are several scripted NPCs in the maps, and 
there is a rather detailed description of what CFDialog does. What the heck 
was I supposed to add ? A youtube video of clay characters visually 
explaining how to type "P.Y.T.H.O.N" using the keyboard ?

> Presently I think it is difficult for a map developer to know how to use the 
facility.
>
For a map-maker that doesn't even bother to read the provided docs, yes, it 
is.

> With some mention, cross-linking, and a better example, more than likely
> the author's work _will_ be far better appreciated, and maybe even used.
>
A *better* example ? Fido Damn It(tm), the example is a two-level-deep "hello 
world" style dialog ! What by the gods am I supposed to find as a "better" 
example for a class used to provide scripted *dialogs* ?

For reference, the example provided in the Wiki contains 20 lines of code (the 
rest of the content being comments). 6 of those are either required imports 
or variable definitions. This leaves 14 lines that are specific to the use of 
CFDialog. Should I conclude that 14 lines is already too complex for a 
two-level dialog with three different answer branches ? Was I expected to 
make one-liner examples only ?

Cross-linking ? More mention ?

Do you realize that a search on "dialog" on the Wiki returns the CFDialog 
documentation as the *first* result ? Same for "speech" ? That it is the 5th 
result on "npc script" ? The only one on "npc answer" ? The first one on "npc 
answer" ?

Or maybe "CFDialog" is not an explicit enough name ? Maybe I should have 
named "doc/Developers/python" "this-is-the-doc-related-to-scripting-stuff-using-python-use-a-text-editor-to-open" ?

I'm sorry if I'm feeling my temper on this, but that's really BS. Any 
2-minutes search on the Wiki would have told you what you needed to know 
about the extension alongside with an example script  (heck, I didn't even 
know which keywords would have worked to find the cfdialog page - I just 
tried the first words coming into my mind on that topic !). Now, if even a 
search in the Wiki is asking too much to a map-maker, then maybe we should 
plainly ask the question of the pertinence of maintaining a documentation 
wiki in the first place.