[Discussion] Mission statement

[mark-wiemer]

Clarify:

1. What dev.luanti.org (DLO) will do, i.e. replace other official doc sites, ref [discussion]: wiki and dev wiki merging #12 and [Discussion]: Merge with minetest_docs project, unify all documentation #19
2. What DLO won't do, e.g. game-specific docs

Currently we have broad approval in GH and IRC of using DLO to replace all other official doc sites, esp. minetest_docs (#19), lua_api.md (#47), VoxelManip wiki (#32), and wiki.luanti.org (#15). I don't think we need to emphasize this to readers too much as it will become clear as links start redirecting, and maybe an announcement can be make when DLO is more mature.

For what DLO won't do, we can maybe add some disclaimer near the homepage about it? What other things might folks expect DLO to do that we should clarify it won't do? Teach you how to cheat? Just spitballing :)

[appgurueu]

What DLO will do: Offer supplementary documentation both for engine internals / engine dev processes and mod development. This supplementary documentation may become outdated, though we will do our best to keep it up to date.

What DLO will not do: Offer guaranteed up to date, normative documentation. If something isn't right here, that's a doc issue, not an engine issue; it's a one-way street (for now): This project documents the engine, but what's documented here does not decide what the engine has to do and PRs need not update this project.

And as you've already said, of course nothing game- or mod-specific belongs here (worth stating because the old wiki did have this in scope).

[GreenXenith]

This is my rationale and proposal for a mission statement and a roadmap. Both are critical to make sense of what we have going on here.

It seems most of the team supports #19 (unifying documentation). This means merging the original Dev Wiki, "Player" Wiki, and minetest_docs (which has already begun). Each has goals and problems:

• The developer wiki documented various engine patterns/concept, tools, ways to work with the API, examples etc. These should be in line with the engine itself and don't have much room for subjectivity and should remain up to date. They were not up to date or organized, user edits were infrequent.
• The "player" wiki documents things relative to people using Luanti to play games. How to get content, what controls Luanti currently opinionates, servers, etc. These should also be in line with what the engine supports and also doesn't have much room for subjectivity and should remain up to date. It is not up to date, contains a lot of irrelevant (MTG) content, and user edits were again infrequent.
• The goal of minetest_docs is to thoroughly document the entire Lua API and provide examples and references. It is intended to replace lua_api.md. It was working on it, but lack of practical planning led us to use tooling we weren't comfortable with and we lost motivation.

To me it seems that the wikis should not really have been wikis, but that was a byproduct from when Minetest was a game. It isn't any more. Wiki-style user edits don't make sense for content that should be based on objective features the engine provides. Major content edits need proper review (even if non-comprehensive) and guidelines. Minor edits can be compiled in trivial PRs. There is also a team dedicated to documentation.

The minetest_docs goal hasn't changed. It (and the rest of the project) just needs sufficient "WORK IN PROGRESS" labeling.

Mission Statement

Luanti Documentation will be the central resource for the Luanti project as a whole where contributors and writers collaborate to author well-tested, understandable, categorized, and searchable information based on the current state of the Luanti engine. Documentation will cover:

• Comprehensive API reference, examples, and guides
• Engine reference and internal structures
• Server and platform (player-facing) usage and guides

Roadmap

• (Short term) Migrate Dev Wiki content
• (Immediate) Site notice to users of WIP project state and mission statement and roadmap (Add "new site" info banner #71)
• (Short term) Migrate relevant Player Wiki content (Stuff to move from wiki.luanti.org #15, Importing content from the Voxelmanip Wiki #32)
• (Short term) Categorize information by target audience (API users, engine developers, server owners, players, etc.)
• (Short term) Set contribution guidelines (Add contribution guidelines #60)
• (Medium term) Develop build workflows (Standard build pipeline #73, might be changes later)
• (Medium term) Improve site theme and accessibility (Standard accessibility checks #72, others)
• (Long term) Refocus and continue API reference efforts
• (Long term) Once proven successful, introduce LDoc annotations to the engine (this is a Docs Team job)

Open to discussion. Whatever ends up being accepted as a mission statement/roadmap should be added to the repo and we should probably utilize the GitHub projects boards.

[mark-wiemer]

Ref #71 ;)

[mark-wiemer]

100% agree, great writeup :)

[appgurueu]

I agree that this is a good mission statement, but I feel compelled to point out the obvious: It is very ambitious. I don't think the failure of the (less ambitious) initial minetest_docs project can be blamed solely on our choice of tooling.

Given the momentum I've seen in the past days, I am optimistic. If this did end up being implemented as planned, that would be great. One thing that's different is that we now start out with a website under an official luanti subdomain, much better than some sorry files that can be viewed (poorly) on GitHub.

Once the short- and medium-term goals have been achieved, we need to spread the word to gain mass, to attract readers and writers alike. Writers lose motivation and lack feedback if there are no readers; readers may turn into writers eventually.

[mark-wiemer]

I don't see anything wrong with shooting for the moon, sometimes you need to be irrationally optimistic! My mindset will continue to be "open issues for problems, focus on one issue at a time" and soon enough we'll have a great feel for what we need to work and and we'll be able to get it done quickly :)

[GreenXenith]

It is very ambitious.

I don't see it as ambitious given the timeframe. The original goal is almost already completed, and further improvements are already taking place. The minetest_docs goal was long term anyway.

I don't think the failure of the (less ambitious) initial minetest_docs project can be blamed solely on our choice of tooling.

I apologize for making it sound like the sole cause; I know for me at least, I would have contributed a lot more if I didn't have to figure out AsciiDoc every time I went to try writing pages. It also would have made copying existing markdown from the lua_api.md easier, and the familiar system would attract more contributors. And a lack of rendering meant contributions weren't as meaningful. I personally believe a lot of blame eventually reaches the choice of format and tools, and we identified these problems recently with the intent to adopt markdown and a well-supported converter/renderer-- but this project did it even better.

If this did end up being implemented as planned, that would be great.

The point of a mission statement and roadmap is to define clear goalposts. It doesn't matter if it takes a while, following the plan will eventually allow this to become the central documentation. And as we complete tasks, we can expand details for later goals (like the API reference) to define granular tasks and plans.