Include version information in doc directories

[blueyed]

Via #64:

the current URL suffix for the stable branch docs is called doc/api, isn't it better to rename it to something related to that specific stable version (like /api/v4.0) for example.

Yes, we should include the version in the docs we are building, and then have a api symlink to the current one.

This would mean to not overwrite old docs when pushing it to https://github.com/awesomeWM/awesomeWM.github.io probably?

[aajjbb]

This would mean to not overwrite old docs when pushing it to https://github.com/awesomeWM/awesomeWM.github.io probably?

I do think so, at least for 'stable' versions. I'm not sure how's the flow of awesome versioning, but we could keep 'key releases' (something similar to a LTS) and keep their docs.

[blueyed]

I do think so, at least for 'stable' versions.

We should only have subdirs based on stable versions, i.e. based on some Git tag.

I'm not sure how's the flow of awesome versioning

WIP, but doing good.. ;)

but we could keep 'key releases' (something similar to a LTS) and keep their docs.

I think we should not delete anything there when updating the gh-pages repo, and could then remove versions from there later / on demand.

[psychon]

This would mean to not overwrite old docs when pushing it to https://github.com/awesomeWM/awesomeWM.github.io probably?

I would prefer if the web page were "reproducibly buildable" instead of containing "random cruft that we accumulated over time". That seems safer to me.

and then have a api symlink to the current one.

Would all our own links go to, let's say, api/current? If so, how would one learn about older API docs that are available. Put different: Would anyone find this?

Also, I had the impression that Elv13 wants people to upgrade to the latest version of awesome instead of staying with older, more-or-less-working versions. Such a goal would conflict with keeping old docs around.
CC @Elv13

[blueyed]

Put different: Would anyone find this?

It could be linked to from /doc, of course.

[Elv13]

Also, I had the impression that Elv13 wants people to upgrade to the latest version of awesome instead of staying with older, more-or-less-working versions

That's your idea ;) You started asking people to test with git when reporting issues. Then given Awesome 3.5.* was obviously dead and unsupported[1], I followed suit and told/pushed/harassed users to upgrade[2][3]. But right, I did say that for about a year and told users who wanted 3.5.x doc to build it themselves or use the copy installed on their system. The wiki is still an open issue. There is useful content, but no "good" dump[4].

I am not an army and I can't support users of 3 different era of the project. I also don't write code for questions anymore. I give links and add answers to the doc. I can't document the past all the way back to 1.0. I am not against users using old versions, but I wont support them.

[1] Neither of us have seriously backported patches/fixes for 12 months.
[2] I am doing support on IRC and got bored of 3.4 users, then got bored of 3.5 ones.
[3] The 3.5 doc / wiki was unusable for "tech support", I could not just give them a link: it was either wrong or incomplete.
[4]archive.org links are broken, the markdown dump is missing half the pages and the HTML one unusable)

[aajjbb]

So, keeping only the docs of the latest stable version and the git version is better. If so, I believe changing URL's to more informative ones is enough. Something like /apidoc/git/ and /apidoc/v4/

[actionless]

i think we still need to rename it, probably just to these two URIS:

• /apidoc/stable

• /apidoc/latest

[sclu1034]

I agree that some renaming is needed, as the current state (/apidoc vs. /doc/api) is just confusing.

But I'd prefer explicit version numbers for releases (e.g. /apidoc/v4.3), as outlined at the top of this issue, to make bookmarks and links more predictable for users.

If we only had a moving target /apidoc/stable, then a blog post written today, linking to what would be v4.3 docs, would become confusing years down the line, when it suddenly links to an incompatible v5.x.

Additionally, I'd say that the git version should be /apidoc/git or /apidoc/master, and that /apidoc/latest should instead be a 302 (temporary redirect) to the current stable version. That way, it can be used where it makes sense (e.g. linked to from the homepage or README), but would not show up in bookmarks or URLs copied out of the address bar.