Deprecated Features and the Wiki

[pancreas]

Hello Everyone[1],


I've been using Love2D in a prototype. I find the documentation, that is to say "the wiki", to be about average for a project of this type, IMHO. I don't think that I have the insights to edit anything, however I do have one observation / suggestion.

I find myself looking at the reference section and then having to always scan the far right column to see which feature has been deprecated and whatnot. It is the most aggravating part of the experience, because it requires me to read the method name, see if it's been deprecated, if it has, keep scanning or go to the deprecated method's wiki page and then see the note about where it is now. Because there are so many deprecated features, this is a pretty significant amount of the experience.

Suggestions:

1: Make a filter for people that are logged in. Only API calls that are for that version are displayed.
or
2: Sort by: deprecated (blank first, oldest-newest) and then alphabetical
or
3: Some better idea.

If this isn't the correct place to put this, then you have my apologies. The discussion page on the wiki might be better, but i didn't think a page that advertised the "almost complete" status of the 0.6.2 documentation as a hotbed of discussion.

-Andrew


[1] I'm new here, and so that constitutes my introduction... and so does this. For context, I've been programming in Lua for a while, but my overall experience with professional programming is limited. I work for Tightrope Media Systems.

[slime]

Welcome!

I find myself looking at the reference section and then having to always scan the far right column to see which feature has been deprecated and whatnot. It is the most aggravating part of the experience, because it requires me to read the method name, see if it's been deprecated, if it has, keep scanning or go to the deprecated method's wiki page and then see the note about where it is now. Because there are so many deprecated features, this is a pretty significant amount of the experience.

Suggestions:

1: Make a filter for people that are logged in. Only API calls that are for that version are displayed.
or
2: Sort by: deprecated (blank first, oldest-newest) and then alphabetical
or
3: Some better idea.

Yeah, it's pretty frustrating for me as well (being the person who's largely responsible for adding new changes to the wiki) – and it's only going to get worse once [wiki]0.10.0[/wiki] comes out. SMW doesn't make it easy to filter out wiki pages by 'removed version', as far as I know.
If anyone has suggestions that work well with SMW I'm all ears.

Someone did make a Chrome extension script for that, although I haven't tried it yet myself: https://gist.github.com/airstruck/1603d55d79c469ac9fa6

[s-ol]

Welcome!
-snip-
Yeah, it's pretty frustrating for me as well (being the person who's largely responsible for adding new changes to the wiki) – and it's only going to get worse once [wiki]0.10.0[/wiki] comes out. SMW doesn't make it easy to filter out wiki pages by 'removed version', as far as I know.
If anyone has suggestions that work well with SMW I'm all ears.

Someone did make a Chrome extension script for that, although I haven't tried it yet myself: https://gist.github.com/airstruck/1603d55d79c469ac9fa6

if that script works, you should be able to include it in the wiki template, no?

[Jasoco]

I agree I'd like to have an option to filter out features that were removed and don't apply to the current version. I never use an older version anymore and always switch as soon as I can. It just gets confusing sometimes.

[josefnpat]

For maintenance of older projects and in the rare case I do use an older version, the depreciation guide is vital. Please do not remove that information!

That aside, it can get annoying. Perhaps some visual restructuring with a header of "Deprecated Features" might help?

[s-ol]

Okay, I just tried the gist you linked above, and it works flawlessy. The two things marked "TODO" at the top of it should ofc be implemented still.

Also another very nitpicky idea: if the hosting package allows it, maybe subdomains for forum and wiki would be a good idea? For me personally it wold make visiting either simpler. I don't know whether the current SSL cert has a wildcard subdomain either.

[airstruck]

That script should work in any modern browser (and if it doesn't, it won't be hard to fix). I think it would be best to modify the wiki templates with things the script can look for (data- attributes, probably) instead of having to scrape the human-readable stuff. I started on this, but haven't updated the script to look for it yet. I probably won't be working on it much for a while, so if anyone else wants to take over, please feel free.

[Evine]

A simple suggestion would to color the backdrop of the entire line when it's deprecated, then you'll still be able to read the list of functions without having to scan the right side to see if it's deprecated.

[davisdude]

Or make it like GitHub: You can browse the "repository" at any point of releases. This would take a lot of files, etc. but would improve ease of use IMO.

[bartbes]

SMW doesn't make it easy to filter out wiki pages by 'removed version', as far as I know.

That's actually not too hard, but there just doesn't seem to be a way to not filter out pages without a 'removed version' tag (so functions that haven't been removed, for example).