## Documentation is pretty, bland.

General discussion about LÖVE, Lua, game development, puns, and unicorns.
JSharpe
Prole
Posts: 6
Joined: Mon Jul 27, 2009 4:48 pm
Location: UK
Contact:

### Documentation is pretty, bland.

So i thought i might give LOVE a try, though the documentation is pretty bland and empty.

Compared to other Wiki's and Documentation I've seen, I'd have thought to see a lot more detail in how to use functions within LOVE. I always read through the wiki briefly to study how I should code a game in the environment.

Take for example this;

http://love2d.org/docs/love_graphics_setColor_2.html When i first looked at it, I was thinking, set the colour of what? Can i change colours of images with this, maybe an object i created? How am i meant to use it at all?

Is it not possible to add in information about functions and elaborate on how they work, where they should be running? Maybe move the whole documentation over to the wiki side for the community to edit and place in examples of efficient, effective code.

An example of what I'd like to see (information wise) is this; http://wiki.garrysmod.com/?title=Entity.SetColor

Compaired to the LOVE documentation on SetColor there's a lot more information on how it should be used.

I asked in IRC and they seem to agree with my point of view.

qubodup
Inner party member
Posts: 775
Joined: Sat Jun 21, 2008 9:21 pm
Location: Berlin, Germany
Contact:

### Re: Documentation is pretty, bland.

I also now think that the documentation should be wiki-ish.

Does anyone want to suggest a documentation system, that makes it possible for guests to submit alternative versions of pages and that makes it *easy* for the admins to accept/decline these suggestions? (Easy as in not having to copy-paste anything, simply click yes or noes.)? Perhaps it would suit them developer dudes.
lg.newImage("cat.png") -- made possible by lg = love.graphics
-- Don't force fullscreen (it frustrates those who want to try your game real quick) -- Develop for 1280x720 (so people can make HD videos)

Pliskin09
Citizen
Posts: 89
Joined: Fri Jul 24, 2009 8:30 am

### Re: Documentation is pretty, bland.

nope, but should not be too difficult to write up

Robin
The Omniscient
Posts: 6506
Joined: Fri Feb 20, 2009 4:29 pm
Location: The Netherlands
Contact:

### Re: Documentation is pretty, bland.

I agree with the OP.

qubodup: why not just use the wiki?

Pliskin09
Citizen
Posts: 89
Joined: Fri Jul 24, 2009 8:30 am

### Re: Documentation is pretty, bland.

to be honest i find it very hard to find stuff on that wiki. theres no where to get you started and you need to know what to search for before you get anything to come up. (unlike with the documentation area, where everything is very easy to find. )

Robin
The Omniscient
Posts: 6506
Joined: Fri Feb 20, 2009 4:29 pm
Location: The Netherlands
Contact:

### Re: Documentation is pretty, bland.

Pliskin09 wrote:to be honest i find it very hard to find stuff on that wiki. theres no where to get you started and you need to know what to search for before you get anything to come up.
Which can be changed. It's a wiki! I'd do it myself, right now, but I'm on a rather tight schedule this summer. Any volunteers?

Arthurio
Prole
Posts: 8
Joined: Sun Jul 12, 2009 7:12 pm

### Re: Documentation is pretty, bland.

I wholeheartedly support this. The current documentation is lacking to say the least.
Imo there should be:
3) examples!! and links to examples! with code, screenshots and .love!

Lets just use the wiki, don't be afraid of your users, assign mods.
Anyway I'm willing to contribute with however little I may have.

rude
Posts: 1051
Joined: Mon Feb 04, 2008 3:58 pm
Location: Oslo, Norway

### Re: Documentation is pretty, bland.

Using the wiki or any existing wiki systems I know of is out of the question. It would involve a maintenance nightmare we do not have the capacity to solve. It would have to be a new smarter system. If you add a function, for instance, it should automatically appear in relevant pages, such as the list of functions in the parent. Another example is a subclass: it should be enough to state that a class is a subclass of another class, and functions from the superclass should appear automatically in the function listing of the subclass. If a system like this already exists, please let me know.

As qubodup says, changes should be approved by a developer before it's released, so there's at least a chance the information in the documentation is correct.

(OP: I must say your link to Entity.SetColor made me laugh, as it was a decent example of why documentation should not be wikified. It has worthless listing of "information" like "first value is red", and the example had lots of irrelevant code. )

Robin
The Omniscient
Posts: 6506
Joined: Fri Feb 20, 2009 4:29 pm
Location: The Netherlands
Contact:

### Re: Documentation is pretty, bland.

Maybe. But I'm still in favour of adding more extra and detailed information to the wiki.

And as for that "new smarter system": what you say about that reminds me of Doxygen. I've never used it myself, so I don't know if it can do all that.

JSharpe
Prole
Posts: 6
Joined: Mon Jul 27, 2009 4:48 pm
Location: UK
Contact:

### Re: Documentation is pretty, bland.

rude wrote: (OP: I must say your link to Entity.SetColor made me laugh, as it was a decent example of why documentation should not be wikified. It has worthless listing of "information" like "first value is red", and the example had lots of irrelevant code. )
Yes that example i posted shows some information that is not necessarily needed or connected to the function.

Though i'd prefer seeing that than looking at this; http://love2d.org/docs/love_graphics_ne ... ont_1.html and thinking how I am going to pass on a glyphs,

Should i do them like this;

Code: Select all

"ABCDEFG"
"A B C D E F G"
chars = {"a", "A", "b", "B", "c", "C"}