To anyone complaining about Ren'Py's documentation...

[PyTom]

http://cekirdek.pardus.org.tr/~ismail/ffmpeg-docs/

(And, just to be fair, http://www.dranger.com/ffmpeg/tutorial01.html )

[Asceai]

If you want to know any specifics about ffmpeg/lavc, post and ask. =P The developers are admittedly the 'the source code is the documentation' kind.

And yes, the source code is horrible too

[Jake]

The developers are admittedly the 'the source code is the documentation' kind.

In my experience, you can pretty much guarantee that anyone who says "the source code is the documentation" or "anyone who is a programmer can read code, so I don't need to write comments/documentation" writes the hardest code to read ever. And quite often the most unnecessarily-convoluted and badly-laid-out.

[Preludian]

Ok, I will never ever complain anymore

.
.
.

But it could use some enhancements

Ever had a look at the community blitz3d documentation I mentioned some times ago?
.
.
.
bye

[Asceai]

And quite often the most unnecessarily-convoluted and badly-laid-out.

Well, in the case of ffmpeg/lavc, it actually makes perfect sense to an ffmpeg/lavc developer.

To outsiders it's a bit of a doozy, though.

[killdream]

I think Ren'Py docs are pretty good. Just sometimes I found myself wondering about what kind of data were returned in some functions. But, well, it was in inner functions that should be private =D I just realized it because my battle system doesn't work in Ren'Py 6.9 -.-

[Jake]

I think Ren'Py docs are pretty good.

The problem with the Ren'Py docs is that they're pretty good... for programmer's documentation. From a programmer's point of view, I don't have many complaints about Ren'Py's docs, they're some of the best I've seen for an open-source freely-distributed API. (Which also says a lot about other open-source, freely-distributed APIs, but that's irrelevant.)

The problem with Ren'Py's docs is that the set of people who are capable of telling a good story and/or producing art for that story has a very small intersection with the set of people who are programmers and can read programmer's documentation.

[Preludian]

IMHO the reference should be made clearer, more for a standard hobbiest-programmer and with examples for every command. In every book about any languages good examples are key. Small functional examples.

[PyTom]

I'm quite aware that the Ren'Py documentation can be improved. That's why it's on a wiki.

I'm just pointing out that it could be far, far, far worse. (And to be fair, I've been able to accomplish most of what I've needed to with ffmpeg.)

[Preludian]

yes of course, I am complaining on a very high level. You already have a documentation that is very nice, even compared to many full-price products. I only wanted to point out, that although RenPy itself is also (mainly?) aimed at the non-programmer, the current reference needs the knowledge of a proficient programmer for anything but standard stuff. Most often a small example would suffice to explain what many words cannot do.

[killdream]

Hm, but aren't the non-standard stuffs python based? I think even if you wanted more standing out effects in your game you should learn Python (isn't that difficult, even to those that aren't programmers), since they're the base of Ren'Py. And understanding the basics is fundamental, IMO.

But, of course, examples would be great. I mean, good examples of how do this and that. But, well, we can't require Pytom to manage the docs and Ren'Py coding, since it's an OpenSource project and he has his own life too.

So, since it's a wiki, community members should help improving it.

[JQuartz]

Python (isn't that difficult, even to those that aren't programmers)

Eh, Python is difficult for non-programmers. Actually any programming language is difficult for non-programmers. But yeah, if you want to make your game have some non standard function, it's your responsibility to learn the language. It's similar to a motocyclist who wants to pilot a plane. You can't expect a plane's piloting system be made the same as a motorbike.

[killdream]

Oh, I just mean that Python is more simple than most programming language and it's somewhat easy to learn too.

[Watercolorheart]

I find the Wiki and Demo quite easy to use, once I got over the intimidation factor. Now those newbie errors, I think we should make a "common errors and fixes" lint FAQ ... I'd be willing to try to help. Especially since I am all-too-prone to them, coding in Jedit, Notepad, and Scite between five different computers in any given week.

That first link is so LOL.

[Preludian]

Hmm, well actually I find most other languages easier to learn than python, don't know why, maybe because it's so different in many/most aspects. But it's ok, I have already added some functions I needed to my vn, so python is not exactly my problem. It's more that I can't use the real advanced renpy features, because I sometimes don't actually understand what it's for or how to use it.

I have a idea, would it be ok to add questions in the wiki, where I or others could need some more in depth explanations by some 'real-programmers'? The question could then be asked here and the answer or example then edited in the wiki or linked here.