Rethinking the documentation

[Santos]

Dumb ideas ahead!

(Backstory: I think a manual for LOVE should exist. I reference it a few times here.)

If you want, take a look at the wiki and ask:
- What is there?
- Is it useful?
- If it is useful, or could be useful, how could it better achieve its goals?

Here's my take on it:

The front page of the wiki features:
- An unorganised grid of links to other pages.
- Links to Lua references/tutorials, which are only useful if you already know how to program.
- The same hello world example from the home page.


Getting Started and Game Distribution are useful and this information should be covered in the LOVE manual. What's missing is discussion of what LOVE actually is, why someone would choose LOVE over alternatives, what version of Lua LOVE uses, etc.


Building LÖVE: Relevant info is/should be on Bitbucket, so this page seems unnecessary.


License: The license is already mentioned on the home page and comes with LOVE when you download it. It's not clear what the "old, imported documentation" is that is licensed under the FreeBSD Documentation license. This page seems unnecessary.


Software: Lists some assorted software which might be used for game development. This page seems unnecessary. I'm sure there are other lists of useful software for game development out there. Information on tool support for LOVE is important though, stuff like debuggers for LOVE, LOVE-related plugins for text editors, etc., but this stuff is listed among software unrelated to LOVE.


Snippets

Problems:
- No organisation.
- Unclear licensing.
- No quality control.
- Some are LOVE specific, some aren't.
- Some are basically libraries.

Alternative:
- Libraries: more complete, clear licensing.


Libraries

Problems:
- Many available libraries aren't listed. The only libraries listed are those which someone has bothered to make a wiki page for.
- Almost no organisation.
- Some don't work with the current version of LOVE.
- Some are LOVE specific, some aren't.
- No quality control.
- There isn't a place on the wiki for LOVE-related tools which aren't libraries.

Alternatives:
- The Libraries and Tools subforum: lots more libraries and enables discussion.
- awesome-love2d: curated and organised.


Games

Problems:
- Many games aren't listed. The only games listed are those which someone has bothered to make a wiki page for.
- None or few of them run with the current version of LOVE.

Alternatives:
- The Games and Creations subforum: lots more games.
- josefnpat's list of notable LOVE games.
- Vapor (which is like Steam for free LOVE games), although it uses an older version of LOVE.


Tutorials

Problems:
- The page currently has all of the languages together, and you need to click "further results" to see all of the tutorials.
- Also they're unorganised.
- Some tutorials just describe LOVE functionality (which is what the manual would do).
- The wiki is a limited (although accessible) way of authoring tutorials.

Alternatives:
- A subforum for tutorials. It would contain less topics than other subforums, but it would make it easy to find tutorials and hopefully would encourage people to make and talk about tutorials.
- The LOVE community blogs.
- A curated list of tutorials. awesome-love2d already has a couple.
- I think an expanded beginner tutorial like Hamster Ball would be useful. Even though Hamster Ball is simple it still introduces some key LOVE concepts, including callbacks, objects, using dt, etc. Maybe a tutorial like this, with the intention to introduce LOVE concepts but covering more ground than Hamster Ball, could be included in the manual or be created separately.


API reference

Problems:
- Mostly unorganised except by module/type/alphabetical sorting.
- Get/set entries not organised together, creating longer lists of functions.
- Function descriptions next to function names when listed are often useless, for example "love.graphics.setBackgroundColor" has "Sets the background color.".
- Constructor functions are redundantly listed both on the module and object pages.
- Unusable things are still documented (love.font, love.filesystem.init, love.filesystem.setSource).

Ideas:

I think having the documentation in a simple structured format like a Lua table has advantages. It can be used to format the documentation however you want (I've experimented with a single page, which seems faster to navigate than having multiple pages, but you could also generate multiple pages from the same data).

It's still editable like a wiki through pull requests, and I don't think contributors even need version control software with the in-browser editing GitHub has.

There's still stuff which hasn't been done in the project linked to above, like images and languages other than English and links to other sections, but that's all possible.

The manual should include and expand upon the high-level introductions given on the module pages and the examples on the function pages. I think examples are better suited for the manual because I would assume that useful examples involve more than one function, and therefore don't fully belong on any particular function's page.


Version History: great! I think it would also be good to have guides for exactly what you need to do to update your game to the latest version of LOVE.


So in conclusion, LOVE's documentation could consist of:

- The manual
- The reference
- A "curated list of curated lists", e.g. links to awesome-love2d, josefnpat's list of notable LOVE games, etc.
- A page about tool support (maybe hosted on GitHub for collaboration?)
- A page for version history and migration guides

And also the Bitbucket README, the blogs, and the forums (with a subforum for tutorials).

[Sheepolution]

I agree that the wiki is quite a mess. I actually tried cleaning it up recently but found out that this was a task that was too big to handle all by myself. There are a lot of garbage pages on the wiki. Either outdated or a stub. But I'm not sure what to do. We could start removing a lot of garbage pages. Should we start moderating new pages? I agree that the wiki can use some work but I'm not sure if drastic changes like you mentioned are necessary.

I have to disagree with the API reference though.

Constructor functions are redundantly listed both on the module and object pages.

I don't see why redundancy like this is a bad thing.

[raidho36]

Ideas are good and all but someone has to go and do it.

[ivan]

One thing I would point out is that there are two types of libraries:
- love2d-dependent libraries
- pure Lua libraries
This is an important distinction in my opinion, since the "pure Lua" libraries can be used anywhere and even without Love2D.
The "awesome-love2d" list can be trimmed a lot, considering that
serialization, tweening, object-orientation and math are basically generic Lua libraries
that have nothing to do with Love2D apart from being developed by Love2D forum members.
I have a lot of respect for the pure Lua libraries (in fact I wrote of few these myself),
but it seems to me that there should be 2 separate lists.

[Positive07]

What Ivan said is true, even Bump is a pure Lua library...

I would start this as a repository in Github, maybe under the LÖVE Community organization, write this in markdown and start it up.

I think that the wiki is fine as it is, but we are lacking a place to find "completed" LÖVE games, usable LÖVE libraries, and Lua libraries which may be of interest to LÖVE users.

In addition to that the manual you described is another cool concept that could improve LÖVE's documentation a lot.

TL;DR: Yes there is lots of crap in the wiki, the reference is fine the rest is not. awesome-love2d is too filtered or something, it should grow since there are far more libraries here. Github sounds a good idea for collaboration. The manual is a great idea

[zorg]

Okay, so:

So in conclusion, LOVE's documentation could consist of:
- The manual
- The reference
- A "curated list of curated lists", e.g. links to awesome-love2d, josefnpat's list of notable LOVE games, etc.
- A page about tool support (maybe hosted on GitHub for collaboration?)
- A page for version history and migration guides
And also the Bitbucket README, the blogs, and the forums (with a subforum for tutorials).

Of these, i'd weed out a few, so as a start:

• Wiki
  • Reference (Already exists, devs update it for the most part, but others can help out; should only contain small examples, if any, nothing fancy)
  • Manual (I'm currently working on a page example here, akin to how gameprogrammingpatterns.com does it, explaining each facet of a game, instead of the separate modules. Updated by people who want to, but it should be kept up with the new versions; see the notice on the article.) Basically, one place, neatly contained articles, even if they are longer than anything else currently on the wiki.
  • Version History - Already exists on both the wiki and on bitbucket.
• Forum
  • The current subforums, i don't feel like another is needed for tutorials... too many places for new people to search already.
• Bitbucket
  • As said before, version history is here in the source.
  • Readme as well.
• External sites
  • Blogs - Good for banter and specific articles that people want to really do, mostly relating to "interviews" and implementing very specific game functionality, too specific for the manual, since that shouldn't be a "how to do any game" guide, that's too much out of scope, in my opinion.
  • Curated lists - The wiki has a few, including libs, games and tutorials even, but at least the last one is borked, and it's "auto-updated" in the sense that it lists articles with specific categories added. I agree they could use an overhaul, or a deletion. Whichever is easier to actually take care of.

What do you mean by tool support and migration guides though?
For the latter, i could imagine the manual containing something like an appendix, articles like "Migration from 0.8.x to 0.9.x" and such, that's not a bad idea.

Also, link to the other thread you made, that's more about the manual: LINK

[slime]

I think anything "extra" that is created should be very simple to update and change (e.g. it shouldn't be very sprawling or dense) - the only thing worse than a lack of documentation is incorrect documentation, and it will become incorrect in future versions until someone updates it. Since no one's income relies on it being updated, there will not always be someone who has the time and knowledge to update it.

[zorg]

I think anything "extra" that is created should be very simple to update and change (e.g. it shouldn't be very sprawling or dense) - the only thing worse than a lack of documentation is incorrect documentation, and it will become incorrect in future versions until someone updates it. Since no one's income relies on it being updated, there will not always be someone who has the time and knowledge to update it.

Agreed, but the manual could be made so that it only ever gets invalid if there's a new version out. (And that'd be kinda the point, just as with the reference pages.)
With that, it could even be set up in a way, that it automatically notifies you on its pages that haven't yet been updated, where necessary.
Even if those articles would be relatively longer than the reference pages, most of it would not need to actually be edited after creation, since it'd just be filler around the examples.

[raidho36]

Regarding correctness, an automatic documentation generator should be used for that - most places already include basic header documentation. Information from it can be carried over to wiki. It might be a good idea to put template bars on those pages that check if they're out of date and display appropriate notices.

[zorg]

Regarding correctness, an automatic documentation generator should be used for that - most places already include basic header documentation. Information from it can be carried over to wiki. It might be a good idea to put template bars on those pages that check if they're out of date and display appropriate notices.

This might be applicable to the docs part, but the devs already keep it up to date themselves, so it'd be a question whether they want to litter the source with that stuff, or just update the part of the wiki "that's theirs" as they did before and still do now. For a manual, the only thing that would be useful is something like checking if the latest version matches a defined variable or whatever on the manual page articles, and if not, display a notice that currently it's outdated, until someone updates it and edits the version to the newest one.