Future of this project

[appgurueu]

trafficstars

This project seems to be dying from inactivity (we're falling behind latest master in terms of docs more and more rather than closing the gap as per https://github.com/minetest/minetest_docs/issues/16) and I'd like to discuss how we should proceed. Possible options I see:

• Archive the repo, bury the project, cut the losses.
• Try to revive the project, get it rolling again. The last attempt at this ("first sprint": https://github.com/minetest/minetest_docs/issues/38) failed. It seems we, the project members, don't have adequate resources to work on this currently.
• This brings me to the next point: Should we try to attract "documentators" to keep this project going?
• Alternatively, if we decide to bury this project, we should not let the effort so far go to waste. Should we:
  • Try to get it merged into the minetest Markdown docs (requires conversion to Markdown, will send us back to PR hell)?
  • Preserve it by putting it on the wiki (it seems @rollerozxa has been working on this)?

What do you think: Where is this project headed, where should it be headed?

[rollerozxa]

Preserve it by putting it on the wiki (it seems @rollerozxa has been working on this)?

Probably should clarify that what I've been doing is converting the content in minetest_docs into markdown and putting it in a Wiki, not the Minetest Wiki. (the Minetest Wiki uses wikitext, has broken syntax highlighting, slow as molasses performance, and account creation is now completely broken even for wiki admins. generally a terrible place to start any new kind of project on, hence why I'm rolling with my own wiki)

[JosiahWI]

I think it would be good to have these either in Markdown or on a wiki somewhere. If it's helpful to people, we may have opportunities to get contributions, but people need to be aware that it exists before they can find it useful.

[rollerozxa]

So I ended up importing most of it into the Voxelmanip Wiki: https://wiki.voxelmanip.se/wiki/minetest_docs

[GreenXenith]

I was recently reminded of some other issues with the current Minetest documentation, specifically difficulty keeping PRs up to date with a changing doc file and inability to clearly classify sections (as "unstable", for example). Paginated documentation is something that needs to happen.

While markdown can be paginated, it lacks the functions and machine readability of AsciiDoc. I still believe this project should see completion eventually, even if it takes a while. I will do it myself at some point if no one else gets to it first.

[v-rob]

Funny you should mention my PR. I actually find documenting my stuff to be rather fun, and the docs for the latest branch weigh in at ~2,000 lines out of a total lua_api.md size of 13,000 lines, and I still want more code examples. I believe in the importance of accurate and comprehensive documentation--users should never have to experiment with something to understand how to use it since that leads to accidentally relying on bugs.

I have had very little interaction with this project, but I believe there is merit to having very good official documentation. Having documentation under the umbrella of the minetest GitHub organization is a good thing. Unofficial documentation becomes stale very easily (including the quasi-official-ish wiki).

At the very least, even if this project were abandoned, I would love to at least see some of this project's innovations in the official repository, such as split documentation files and an improved format over Markdown. And, while I won't pretend that PR hell doesn't exist, it might be somewhat mitigated if https://gist.github.com/celeron55/bf93a47442e418a629181908f68ffb0f stays in place, since only one core dev (self-)approval is needed. Presumably, that could also be extended to self-approval of documentation PRs by trusted members of this repository.

[JosiahWI]

I believe we already have a different policy in place for this repository than the one used for the engine source. I do not see this in a document in the repository, though. Is this information available somewhere?

EDIT: It's in the proposal gist linked in our README.

All proposed changes must have 1 or more approvals from a Minetest-Docs team member other than the proposer, so as long as said approval is not also contested by another Minetest-Docs team member

[v-rob]

I believe we already have a different policy in place for this repository than the one used for the engine source. I do not see this in a document in the repository, though. Is this information available somewhere?

I was referring to if this project were abandoned, and the potential implications if the documentation were merged with the main Minetest repository.

[Zughy]

I'd say close it, it's been more than one year since the opening of the issue and nothing has really changed. I appreciate @GreenXenith good intentions, but it seems to me they're already busy with many other things (MT related). I'm a fan of Archive the repo, bury the project, cut the losses.