User Documentation

[Kyrodan]

Currently there is mainly technical documentation available. I asked questions here in discussions and many of them were answered. The problem was, that it is not documented anywhere.

So I startet a documentation-showcase with Docusaurus. I took the existing Startpage and the design from yuvomi.cloud and let AI made some work :-)

The current result can be viewed here: https://kyrodan.github.io/yuvomi-docs/
The source-repository is here: https://github.com/Kyrodan/yuvomi-docs

Whats (maybe) missing:
There are currently no translations available. We should discuss, whether english and german should be available for all docs or only for (the currently existing) Startpage and Helper-Pages (legal, imprint, ...)

What do you say?

@ulsklyc: if you are willing to integrate it in your Yuvomi-Repository, then I would continue working on polishing and adding more content. If such documentation is not wanted or with another technical basis, then it's also okay for me. Just let me know.

[ulsklyc]

This is a genuinely useful contribution and your diagnosis is correct: the answers exist, they're just scattered across closed discussions instead of being written down anywhere. I've hit the same thing from the other side - I answered #816 today with a feature that has shipped since v0.93.0 and simply wasn't discoverable.

Before I say yes or no to bringing it into the repository, there are a few things I'd rather settle with you than decide over your head, because they determine how much work you'd be signing up for.

1. The technical base is the open question, and I want to be upfront about it. Yuvomi has a deliberate, permanent no-frameworks/no-bundlers rule (see CONTRIBUTING). It's written for the shipped app, and a separate documentation site is arguably not the app - yuvomi.cloud already lives in docs/ as hand-written HTML with its own tokens. But Docusaurus means React, a build step and node_modules in a repository that has none of that today, so this isn't a formality I can wave through. I haven't decided against it. I'm telling you now rather than after you've written another fifty pages.

2. Who keeps it current? This is the part I'd weigh heaviest. Yuvomi releases often - v2.28.0 is out today. Documentation that drifts is worse than none, because people trust it. If it lives in the repository it becomes my problem at every release, so I need to know whether you're proposing to hand it over or to co-maintain it.

3. Where does the truth live when two places disagree? The repository already has canonical sources: the module table in README, docs/SPEC.md for the data model, tools/installer/env-schema.js for env variables. Documentation that restates those will eventually contradict them. I'd want the docs to point at them rather than copy them.

4. On languages - your own question. My instinct is English as the reference for everything, German where it exists, and no half-translated pages. Yuvomi ships a lot of locales that are key-complete but never actually translated, and I don't want to repeat that shape in the docs.

5. You mention AI did some of the work. No objection in principle, but documentation states what the software does, and a plausible-sounding wrong sentence is expensive. Anything that describes behaviour needs to have been checked against a running instance. If we go ahead, I'll read it that way.

The showcase looks good and the structure is sensible. Give me your thinking on 1 and 2 in particular and we'll take it from there.

[ulsklyc]

@Kyrodan Sorry for the long silence on this - the two questions I raised (technical base, and who keeps it current) are the ones I owe you an answer to, and they need a proper decision rather than a quick reply. That decision is next on my list and I will make it here.

Meanwhile I want to put something in this thread rather than leave it in three separate places, because it is the strongest evidence yet for your diagnosis.

Since I last wrote here, three more people asked for a feature that already exists. All three answers were correct, complete, and posted into a thread nobody will ever search:

Thread	Asked for	Where it has been all along
#816	award points without a task	Grant bonus - the main action on the Rewards page. The field is signed: "A positive value credits, a negative value deducts", so it covers corrections too
#933	notification when a medication is due	It falls out of the schedule, it is not a setting. Two prerequisites: the medication needs a schedule (not just an entry - "as needed" has no planned time by definition), and the account needs a reachable notification channel
#736	a cleaning plan without a cleaning helper	The decay tasks in Housekeeping: task, room, how often, when it was last done. GET/POST /housekeeping/decay-tasks never touches housekeeping_workers - a household with no helper can use that part today

The person in #933 corrected themselves and it worked. The person in #736 was told by another user, not by any documentation. That is three in two weeks, and the same finding as #496 - only phrased more kindly each time.

What I take from it for the content, independent of the technical question:

The first pages do not write themselves from the module list. They write themselves from what people actually fail to find, and that has a pattern: it is never the module that is missing, it is the entry point inside it. "Rewards" is discoverable; that its main button also does corrections is not. "Housekeeping" is discoverable; that half of it has nothing to do with a cleaning helper is not - the name actively points away from it.

So the highest-value page is not "Rewards - an overview". It is closer to "I want to X" → the module, the button, and the one prerequisite people miss. The three rows above are the first three entries, written out. Feel free to lift them verbatim; the wording has already been through a round with the people who asked.

To be clear about what this comment is and is not: it is content, not a commitment to the tooling. Whether the docs live in this repository, and on what technical base, is the question I still owe you, and I do not want to answer it by accumulation - by letting material pile up somewhere until moving it becomes the obvious thing. You asked a straight question and it deserves a straight answer, which is coming.

If you would rather hold off writing until then, that is entirely reasonable and I would not blame you.

[ulsklyc]

@Kyrodan Here is the decision I owed you, and I am sorry it took this long.

The documentation stays yours, in your repository, and Yuvomi links to it properly. I am not bringing it into this repository, and the reason is your second question rather than the first.

On the technical base, to be straight with you: I checked, and there is no guard that would have stopped it. The no-bundlers rule is enforced by tests for the shipped app, and docs/ is not covered by them - yuvomi.cloud already lives there as hand-written HTML. So Docusaurus in this repository would have been a decision, not a rule violation. I could have said yes.

What decided it is maintenance. Between v2.7.0 on 12 August and v2.61.0 today there have been 91 releases across 21 days, 19 of which had at least one, with four days at nine. Documentation that sits in this repository is documentation I owe at that cadence. I would not keep it current, it would drift, and drifted documentation is worse than none because people trust it. That is the honest version. Putting it in and then failing it would be a worse outcome for your work than leaving it where it is.

So what I am doing instead:

• A prominent link from the README and from yuvomi.cloud, marked as community-maintained so nobody mistakes staleness for an official statement.
• Where the app can point at a help page, it points at yours.
• The canonical sources stay where they are and I will keep saying so: the module table in README, docs/SPEC.md for the data model, tools/installer/env-schema.js for env variables. Please link to those rather than restating them, and anything that describes behaviour should be checked against a running instance before it goes up.

Two practical things.

First, your repository has no licence file. Right now that means all rights reserved, which makes it awkward for anyone to contribute to it, and it would block us from lifting anything into this repository later even if we both wanted to. Something permissive would fix both.

Second, on structure: you built nineteen module pages, and I think the more valuable page is the one I described in my last comment here. Not "Rewards, an overview" but "I want to X" pointing at the module, the button, and the one prerequisite people miss. The three rows in that comment are the first three entries, already checked with the people who asked. The module pages are worth having, but that index is what people actually arrive with.

One more thing, said plainly: you have not been back here since 17 August, and this decision had to be one that works whether or not you pick the project up again. If you do, the link stands and I am glad to answer questions in this thread. If you have moved on, that is entirely fair, and the offer to link stays open for anyone who takes it up.