Documentation is pretty, bland.

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

Documentation is pretty, bland.

Post by JSharpe » Mon Jul 27, 2009 9:53 pm

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.

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

Re: Documentation is pretty, bland.

Post by qubodup » Tue Jul 28, 2009 2:23 am

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)

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

Re: Documentation is pretty, bland.

Post by Pliskin09 » Tue Jul 28, 2009 10:11 am

nope, but should not be too difficult to write up :nyu:

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

Re: Documentation is pretty, bland.

Post by Robin » Tue Jul 28, 2009 4:07 pm

I agree with the OP.

qubodup: why not just use the wiki?
Help us help you: attach a .love.

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

Re: Documentation is pretty, bland.

Post by Pliskin09 » Tue Jul 28, 2009 4:16 pm

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. )

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

Re: Documentation is pretty, bland.

Post by Robin » Tue Jul 28, 2009 4:28 pm

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?
Help us help you: attach a .love.

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

Re: Documentation is pretty, bland.

Post by Arthurio » Wed Jul 29, 2009 3:05 am

I wholeheartedly support this. The current documentation is lacking to say the least.
Imo there should be:
1) more info about parameters: min and max values, default values, maybe tips
2) more info about what a particular function or method does
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.

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

Re: Documentation is pretty, bland.

Post by rude » Wed Jul 29, 2009 9:59 am

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. :rofl:)

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

Re: Documentation is pretty, bland.

Post by Robin » Wed Jul 29, 2009 4:18 pm

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.
Help us help you: attach a .love.

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

Re: Documentation is pretty, bland.

Post by JSharpe » Wed Jul 29, 2009 8:29 pm

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. :rofl:)
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"}
There's no information about it.


Another example is http://love2d.org/docs/ConfigFiles.html

I was stuck for 20 minutes thinking what was wrong with my test code. Only to have to look at some one elses work, then find out that "love_version" had to be set as a string. A silly mistake because the documentation didn't have enough information. Just adding in square brackets next to it [string] or [int] and what ever other types there are would have stopped it.

Post Reply

Who is online

Users browsing this forum: Bing [Bot] and 13 guests