Ren'Py Documentation/Wiki

[fullmontis]

This has probably been asked/answered before, but I couldn't find anything up-to-date, so here it is...

Ren'Py is an amazing tool with a... Well, how can I say it... Less than stellar documentation. I don't know the behind-the-scenes so this isn't a critique to anyone in particular, it's just a statement of fact. While the documentation for the most basic stuff (i.e. writing a script, adding new characters, basic animations etc.) is enough to get started, trying to dig deeper into the workings of the engine is like trying to untie an enormous mass of string that has been ammassed for years.

The fact that Ren'Py uses a variety of script languages (screen langage, ATL) and a rather large and in some way unconventional API also demands for good documentation to be used without much migraine. I know there is a cookbook forum, but hacking around fragments of code isn't exactly the best way to learn a new API. I created my first game in Ren'Py by putting together the documentation, bits and pieces of code I found on this forum, the tutorial that comes with Ren'Py and (a lot of) trial and error to do some relatively easy stuff. I started reading directly the source code because it's easier to just go to the source. This is something that can easily scare away some new programmer who is interested in using Ren'Py.

I want to underline that this is NOT a critique to the Ren'Py engine, this forum or anyone else. In fact, this forum has one of the most supportive communities I've ever seen. Ren'Py is an amazing tool and I love using it, it's just that making it do something I want is more hassle than it should be. A good and up-to-date documentation would solve this problem and would create some buzz around the engine and attract some small indie studio to make a visual novel/dating sim/adventure game using this engine.

The main problems/missing features here are, in my opinion:

• - The wiki is out of date and should be updated by adding new/removing old stuff.
  - More step-by-step tutorials, especially for the screen language and ATL
  - More examples/code snippets
  - A community editable wiki for cookbook code (is there one?)
  - a wiki for the "low level" python API that is easier to browse (I think the love2d wiki is a good example)

I'm willing to contribute, but I'm nowhere near expert to actually write useful documentation or tutorials. I'm just trying to drag some attention to this problem.

[xela]

This has probably been asked/answered before, but I couldn't find anything up-to-date, so here it is...

Ren'Py is an amazing tool with a... Well, how can I say it... Less than stellar documentation. I don't know the behind-the-scenes so this isn't a critique to anyone in particular, it's just a statement of fact. While the documentation for the most basic stuff (i.e. writing a script, adding new characters, basic animations etc.) is enough to get started, trying to dig deeper into the workings of the engine is like trying to untie an enormous mass of string that has been ammassed for years.

The fact that Ren'Py uses a variety of script languages (screen langage, ATL) and a rather large and in some way unconventional API also demands for good documentation to be used without much migraine. I know there is a cookbook forum, but hacking around fragments of code isn't exactly the best way to learn a new API. I created my first game in Ren'Py by putting together the documentation, bits and pieces of code I found on this forum, the tutorial that comes with Ren'Py and (a lot of) trial and error to do some relatively easy stuff. I started reading directly the source code because it's easier to just go to the source. This is something that can easily scare away some new programmer who is interested in using Ren'Py.

I want to underline that this is NOT a critique to the Ren'Py engine, this forum or anyone else. In fact, this forum has one of the most supportive communities I've ever seen. Ren'Py is an amazing tool and I love using it, it's just that making it do something I want is more hassle than it should be. A good and up-to-date documentation would solve this problem and would create some buzz around the engine and attract some small indie studio to make a visual novel/dating sim/adventure game using this engine.

The main problems/missing features here are, in my opinion:

• - The wiki is out of date and should be updated by adding new/removing old stuff.
  - More step-by-step tutorials, especially for the screen language and ATL
  - More examples/code snippets
  - A community editable wiki for cookbook code (is there one?)
  - a wiki for the "low level" python API that is easier to browse (I think the love2d wiki is a good example)

I'm willing to contribute, but I'm nowhere near expert to actually write useful documentation or tutorials. I'm just trying to drag some attention to this problem.

\\Ren'Py is pretty amazing

We could make it work if it was community driven, PyTom/any other devs time would be much better spent on actual development (as it is now), making documentation takes almost as much time as actual coding.

Otherwise:

- Wiki can die for all I care, there is a lot of really useful documentation on the site. There is little point in doing things twice.

- ATL is covered on in a very confusing manner but there is a LOT that can be found on forums, in fact after reading all of Elmiwisa's posts, there is now a LOT more ATL and CDD in my game

- Screen language is very well covered, maybe some examples on how to tackle some of the more advanced issues but I've never felt any urgency in it.

- More examples would be nice, however Ren'Py is not Rags or Inform, there are so many ways of doing the same thing and examples would be often hard to agree upon, especially for the "semi-official" documentation. With such a framework, it might actually be more useful for people to spend couple of days reading documentation and questions forums to find their own way that copy-pasting code-snips and ending up with silly looking code nobody, including themselves can read.

- Cookbook section on this forum is very editable, some modules there have versions made by different coders (jigsaw puzzle for example).

- Wiki for a lowlevel python API is a very good idea, currently some of the documentation invites using simple variables instead of classes, often leading to almost impossible to read and error-proned code...

In general, it's not that difficult to figure out RenPy for someone's who's motivated, IRC/Forum/Documentation/Wiki do offer a lot.

[Samu-kun]

I think the documentation after the Quick Start tutorial is pretty much incomprehensible. I've pretty much just figured everything out by asking Pytom for code on IRC or just typing code and seeing what it does.

[fullmontis]

\\Ren'Py is pretty amazing

We could make it work if it was community driven, PyTom/any other devs time would be much better spent on actual development (as it is now), making documentation takes almost as much time as actual coding.

I agree, PyTom and the other developers should definately focus on developing the engine. But I believe that Ren'Py is mature and complex enough to require some proper documentation.
I'm willing to help myself, even thought I'm no expert. I have figured some stuff that could make the life simpler to a lot of ren'Py programmers. And I'm sure there are other experienced programmers which knowledge could be valuable to everyone.

Otherwise:

- Wiki can die for all I care, there is a lot of really useful documentation on the site. There is little point in doing things twice.

- ATL is covered on in a very confusing manner but there is a LOT that can be found on forums, in fact after reading all of Elmiwisa's posts, there is now a LOT more ATL and CDD in my game

- Screen language is very well covered, maybe some examples on how to tackle some of the more advanced issues but I've never felt any urgency in it.

- More examples would be nice, however Ren'Py is not Rags or Inform, there are so many ways of doing the same thing and examples would be often hard to agree upon, especially for the "semi-official" documentation. With such a framework, it might actually be more useful for people to spend couple of days reading documentation and questions forums to find their own way that copy-pasting code-snips and ending up with silly looking code nobody, including themselves can read.

- Cookbook section on this forum is very editable, some modules there have versions made by different coders (jigsaw puzzle for example).

- Wiki for a lowlevel python API is a very good idea, currently some of the documentation invites using simple variables instead of classes, often leading to almost impossible to read and error-proned code...

• - I don't agree with this. There is a lot of stuff on the wiki that isn't in the docs, for example function descriptions and code snippets. It feels more like they have complimentary stuff more than the same stuff twice.
  - Again, forums aren't exactly the best resource for learning code. I know there are a lot of great posts but they get lost after a while (unless they are stickied or frequently bumped) and are easy to miss if you do not frequent the section regularly. Search features on forums are always abysmal so finding a specific problem may require more time than needed. For example, I would have never thought about reading Elmiwisa posts if you didn't tell me about them.
  - The fact is, this isn't about what a single person needs but what the engine can do. If Ren'Py can do some advanced stuff, why not document it? It is a waste in my opinion to have a feature that no one uses because it is too obscure to understand...
  - This may be just me, but I believe that the fact that Ren'Py can do stuff in a lot of ways is exactly the reason why it should be well documented... It can become very confusing very quickly.
  - As above, a forum post does not have the visibility a wiki has.
  - I'm happy we agree at least on one point

In general, it's not that difficult to figure out RenPy for someone's who's motivated, IRC/Forum/Documentation/Wiki do offer a lot.

While this is true, this should not be used as an excuse for lack of good documentation. Good docs can make or break an engine, it is one of the main factor that make a developer choose or discard an engine for their game. Ren'Py is lucky to have an amazing and supportive community, it would be awesome to give all this knowledge more exposure.

[xela]

I used to think that Ren'Py was poorly documented as well, but it's actually not that bad. It's just that some docs assume that the reader has a decent grasp on programming or has read Python styled documentation before.

Another issue is that there are so many things possible with Python/Ren'Py and in so many ways, trying to document all of them is almost suicidal. More examples would be a really good idea but that's what forums are for... Maybe a couple new tutorials for the cookbook would be a good place to start...