A manual for LÖVE
Posted: Wed Oct 26, 2016 1:28 am
Since I figure that I'll never make this myself, I thought I'd post this idea just in case it inspires anyone else. I don't know if I'm right about all this stuff, it's just an idea...
The Problem
To use LOVE effectively, you need to know everything it can do. Not memorize every argument to every function, but know what functionality exists.
To know everything that LOVE does, you have to read the entire wiki.
The wiki serves as a good reference to the API. However, reading the entire wiki for the purpose above is, dare I say, inefficient, ineffective, and isn't something that everyone is going to want to do.
This makes me think that some people aren't using LOVE effectively because of a lack of suitable documentation.
A Solution
A manual for LOVE, giving basically the same information that is in the wiki, but in a way that makes sense to read top-to-bottom.
I don't know exactly what this would look like, but here are some ideas:
The order in which things are presented is important
The wiki mostly orders things by module/type, and alphabetically, which is okay for a reference.
A manual could order things by purpose.
For example, love.resize, love.window.setIcon, and the window options in love.conf are all about the window, so they could be together.
love.lowmemory, t.accelerometerjoystick, and love.system.vibrate are all about mobile devices, so they could be together.
love.run, love.timer.sleep, and love.graphics.present are all about the game loop, so they could be together.
Etc.
Some things might need to be discussed in different ways in different places. For example, some blend modes are important to discuss when talking about Canvases.
The manual doesn't need to be a reference
I think the manual should be complete in the sense that it covers every function/concept, but it doesn't need to list out each function's arguments, for example, because the wiki already does this. But maybe it should, I'm not sure what would be most effective.
The manual might not even need to mention the functions by name if it already describes what the function does and has appropriate links. For example, you might be able to cover basically all of drawing shapes (assuming some stuff has been discussed previously) with just:
Lines and polygons (filled or outlined) can be drawn, and there are convenience functions for drawing rectangles, circles, ellipses and arcs.
< Pictures of what they all look like >
The line width, whether the lines are anti-aliased, and what it look likes when lines join in polygons are based on internal state.
< Pictures of different line widths/styles/join styles >
Explain why things are there, if it's not completely obvious
It's obvious why someone might want to play a sound.
It's not obvious why someone would want to use a Canvas, or a Channel, or a compressed image, or when they should be using scancodes instead of keys, or use a lot of other stuff the API provides.
So, provide example use-cases.
The wiki does/should provide this information, but I think it's extra important for the manual.
Sometimes it might even be useful to discuss why things are designed the way they are if it's not obvious.
Point out convenience functions.
Give code examples
The wiki does/should give code examples, but for the manual the examples don't need to be focused on one particular function.
I can think of two types of code examples which might be useful: examples showing how things are used if it's not obvious, and examples which allow you to "play around" with something to understand it better.
An example of the first type would be some simple but realistic uses of Threads.
An example of the second type might be something which plays around with Sources. It's not using Sources in any advanced or unexpected way, but it might be useful for people to play with to understand how Sources work (it could be expanded to demonstrate spatial effects).
Show images/sound/videos
If it's a graphical thing, show it in an image. If it's an audio thing, have an audio clip. If it's something like ParticleSystems, show a video/GIF.
For example, have a diagram showing what Font:getDescent etc. refers to, or give audio for what the different DistanceModels sound like maybe, or graphs of the effects DistanceModels have.
The wiki does/should have this also.
Have a good introduction
What does LOVE do? What does LOVE not do? Why? When would I want to use LOVE, and when would I want to use something else? How does LOVE compare to alternatives? What's the tool support like? Etc.
Another idea
The manual could also serve as a voice-over script for a video, with the visuals showing function names as they're being discussed maybe, or diagrams, examples, etc.
I think the video format would be great for this, because it's accessible and inviting, it goes by quickly, and the potentially negative aspects about learning from video (difficult to locate a specific piece of information, easy to forget what's been said) aren't that bad because it's just an introduction, not a reference.
Making this happen
I think this would need to be a collaborative effort because it's probably too much work for one person. So, some collaborative setup would be good, maybe a markdown document on GitHub, or a wiki, or a Google Doc, or something.
But, really, I'm not expecting anyone to be interested in making this, or even to agree with the stated problem, let alone the solution. It's just an idea I had.
The Problem
To use LOVE effectively, you need to know everything it can do. Not memorize every argument to every function, but know what functionality exists.
To know everything that LOVE does, you have to read the entire wiki.
The wiki serves as a good reference to the API. However, reading the entire wiki for the purpose above is, dare I say, inefficient, ineffective, and isn't something that everyone is going to want to do.
This makes me think that some people aren't using LOVE effectively because of a lack of suitable documentation.
A Solution
A manual for LOVE, giving basically the same information that is in the wiki, but in a way that makes sense to read top-to-bottom.
I don't know exactly what this would look like, but here are some ideas:
The order in which things are presented is important
The wiki mostly orders things by module/type, and alphabetically, which is okay for a reference.
A manual could order things by purpose.
For example, love.resize, love.window.setIcon, and the window options in love.conf are all about the window, so they could be together.
love.lowmemory, t.accelerometerjoystick, and love.system.vibrate are all about mobile devices, so they could be together.
love.run, love.timer.sleep, and love.graphics.present are all about the game loop, so they could be together.
Etc.
Some things might need to be discussed in different ways in different places. For example, some blend modes are important to discuss when talking about Canvases.
The manual doesn't need to be a reference
I think the manual should be complete in the sense that it covers every function/concept, but it doesn't need to list out each function's arguments, for example, because the wiki already does this. But maybe it should, I'm not sure what would be most effective.
The manual might not even need to mention the functions by name if it already describes what the function does and has appropriate links. For example, you might be able to cover basically all of drawing shapes (assuming some stuff has been discussed previously) with just:
Lines and polygons (filled or outlined) can be drawn, and there are convenience functions for drawing rectangles, circles, ellipses and arcs.
< Pictures of what they all look like >
The line width, whether the lines are anti-aliased, and what it look likes when lines join in polygons are based on internal state.
< Pictures of different line widths/styles/join styles >
Explain why things are there, if it's not completely obvious
It's obvious why someone might want to play a sound.
It's not obvious why someone would want to use a Canvas, or a Channel, or a compressed image, or when they should be using scancodes instead of keys, or use a lot of other stuff the API provides.
So, provide example use-cases.
The wiki does/should provide this information, but I think it's extra important for the manual.
Sometimes it might even be useful to discuss why things are designed the way they are if it's not obvious.
Point out convenience functions.
Give code examples
The wiki does/should give code examples, but for the manual the examples don't need to be focused on one particular function.
I can think of two types of code examples which might be useful: examples showing how things are used if it's not obvious, and examples which allow you to "play around" with something to understand it better.
An example of the first type would be some simple but realistic uses of Threads.
An example of the second type might be something which plays around with Sources. It's not using Sources in any advanced or unexpected way, but it might be useful for people to play with to understand how Sources work (it could be expanded to demonstrate spatial effects).
Code: Select all
function love.load()
source = love.audio.newSource('sound.ogg')
end
function love.keypressed(key)
if key == 'space' then
love.audio.play(source)
elseif key == 'p' then
love.audio.pause(source)
elseif key == 's' then
love.audio.stop(source)
end
end
function love.draw()
love.graphics.print('isPlaying: '..source:isPlaying(), 15, 15)
love.graphics.print('isPaused: '..source:isPaused(), 15, 30)
love.graphics.print('isStopped: '..source:isStopped(), 15, 45)
love.graphics.print('tell: '..source:tell(), 15, 60)
end
If it's a graphical thing, show it in an image. If it's an audio thing, have an audio clip. If it's something like ParticleSystems, show a video/GIF.
For example, have a diagram showing what Font:getDescent etc. refers to, or give audio for what the different DistanceModels sound like maybe, or graphs of the effects DistanceModels have.
The wiki does/should have this also.
Have a good introduction
What does LOVE do? What does LOVE not do? Why? When would I want to use LOVE, and when would I want to use something else? How does LOVE compare to alternatives? What's the tool support like? Etc.
Another idea
The manual could also serve as a voice-over script for a video, with the visuals showing function names as they're being discussed maybe, or diagrams, examples, etc.
I think the video format would be great for this, because it's accessible and inviting, it goes by quickly, and the potentially negative aspects about learning from video (difficult to locate a specific piece of information, easy to forget what's been said) aren't that bad because it's just an introduction, not a reference.
Making this happen
I think this would need to be a collaborative effort because it's probably too much work for one person. So, some collaborative setup would be good, maybe a markdown document on GitHub, or a wiki, or a Google Doc, or something.
But, really, I'm not expecting anyone to be interested in making this, or even to agree with the stated problem, let alone the solution. It's just an idea I had.
" which, to me, is unappealing, but hey; there may be people like that here.
