Translations of README.md

[patricklodder]

Currently, I observe 3 problems with README translations:

1. They are exploding in numbers which is making the repository's root directory a bit of a mess. It started with some translations which would help people find the repository with localized search queries (like "狗狗币核心" for "Dogecoin Core" in Chinese), but has quickly escalated to everyone wanting a readme in their own language or dialect.
2. The translations are cross-linked. Every translation currently links to every translation, which means that every file needs to be edited each time a new translation is added, and that no parallel pull requests are possible. This is a nightmare for managing a consistent set of documents.
3. These translations are providing important information, but do not always get maintained. It is also hard for repository maintainers to track changes because the cross-linking edits the files, so the date a document has changed becomes meaningless.

Although I completely understand that everyone wants their language to be there, for whatever reason, an unmanageable process is no good for maintenance on this repository.

Therefore I want to propose, preferably for the next development branch we create when #3407 is finished because this is a process change, to change the way we do these and other documentation translation a little.

1. Instead of putting documents in the root directory, we create directories for each language that has translated documentation under doc/intl. Although this means that the original intent of these translated README files is no longer the sole scope, this becomes manageable.
2. All translated documents will be indexed in doc/intl/README.md, and the root README.md and doc/README.md are only linking to this file, rather than to each individual translation. This solves having to maintain endless README edits.
3. Translated documents will no longer cross-link each other, which means maintainers can easily see which translations need updates, and translations for different languages can be executed in parallel.
4. All translated documents are required to be up-to-date by release time, or they will be deleted and unlinked from the release (depending on which branching strategy we'll pursue). This prevents distributing outdated information with a release.

This leads to a situation that if someone wants to translate any documentation, this is easy. Just need reviews, and don't need to worry about any other documentation, other than the source. It also means maintainers get a much better grip on the state of documentation and can prevent distributing outdated information.

Open to suggestions.

[slightlyskepticalpotat]

That sounds like a good idea, perhaps with an explanatory TRANSLATING.md somewhere with instructions for translating both documentation and strings in the code.

[patricklodder]

Absolutely! 👍

For the string translation we may want to consider re-integrating transifex, but that's a discussion for later.

[daank-c]

Yeah, this makes sense. Although, I wonder if instead of deleting the files and unlinking them, we could add a line to the top of each README that says "Last updated on (date), for (release)".

Then you wouldn't necessarily need to delete anything if it wasn't maintained, because people would see the last time it was updated. This could save you some work.

[patricklodder]

we could add a line to the top of each README that says "Last updated on (date), for (release)".

Okay. Practical example: Let's assume that we change the branching strategy for the next release (likely if it's gonna be major, because we've discussed that before and the dogecoin-specific strategy is a pain in the butt for many reasons)

Now README_Martian.md is explaining people to make pull requests to branches that don't exist, in Martian. I don't speak Martian so I don't know. Chromatic and Michi also don't speak martian and the one dude on Mars lost connectivity a little after we released. Yes, that's a real scenario, just ask Matt Damon. So Mr Damon puts his pull request on a rocket and when it comes close to Earth it will automatically fail. This dude just spent 3 months building the rocket, all for nothing.

Better to just delete README_Martian.md, because it wasn't maintained anyway.

[daank-c]

😂 okay, true. Better to delete them.

[slightlyskepticalpotat]

Perhaps we could delete on each major? Or decide release-by-release if outdated READMEs need to be deleted.

[patricklodder]

Without joking: one of the toughest things during the release pressure cooker is making sure that new code doesn't break install guides. #3437 highlights documentation that we test too little, and this is documentation that we can write notes to as maintainers, for example like I did to the OpenBSD guide, because we speak the language.

Of course preemptive deletion is BS, we'd have to make an issue and put up warnings what needs to be looked at. But sometimes this won't happen, and then we need to just delete and unlink it (from the release, not from the repo; which happens to be easier if we switch branching strategies, fwiw)

[chromatic]

Chromatic and Michi also don't speak martian

I can order astronaut ice cream and reproduce compilation errors in Martian, but point taken.

Localized READMEs are a little bit like obscure platforms: without someone actively maintaining them, they can be worse than no support, because they offer the illusion of support without the accountability of accuracy.

[patricklodder]

Bad assumption on my end, I stand corrected!

[qlpqlp]

Can I propose something a little different and more organised and accessible IMHO?

Like we are doing here:
https://github.com/dogeorg/libdogecoin-docs

and you can se it running on Github Pages here:
https://lib.dogecoin.org/

it uses a workflow to use MDBOOK and so we can have a compreensive easy to understand readme, multilanguage, searchable

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # To push a branch 
      pull-requests: write  # To create a PR from that branch
    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
    - name: Install latest mdbook
      run: |
        tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
        url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
        mkdir mdbook
        curl -sSL $url | tar -xz --directory=./mdbook
        echo `pwd`/mdbook >> $GITHUB_PATH
    - name: Deploy GitHub Pages
      run: |
        # This assumes your book is in the root of your repository.
        # Just add a `cd` here if you need to change to another directory.
        mdbook build
        git worktree add gh-pages
        git config user.name "Deploy from CI"
        git config user.email ""
        cd gh-pages
        # Delete the ref to avoid keeping history.
        git update-ref -d refs/heads/gh-pages
        rm -rf *
        mv ../book/* .
        mv ../CNAME .
        git add .
        git commit -m "Deploy $GITHUB_SHA to gh-pages"
        git push --force --set-upstream origin gh-pages

we could create a branch exclusively for the documentation on CORE, example docs-master and docs-1.14.7-dev ... to not confuse with CORE code, and anyone contributing would be also more easy to translate all other documentation that is available only in english like in https://github.com/dogecoin/dogecoin/tree/master/doc

├── book
└── src
    ├── en
    │   ├── README.md
    │   ├── bips.md
    │   ├── .....md
    │   └── zmq.md
    ├── fr
    │   ├── README.md
    │   ├── bips.md
    │   ├── .....md
    │   └── zmq.md
    ├── ru
    │   ├── README.md
    │   ├── bips.md
    │   ├── .....md
    │   └── zmq.md
    └── SUMMARY.md

[patricklodder]

Good idea!

If you're going to segregate documentation from the code by making another branch, then you can already do this today. Feel free to, within the clause of the MIT license, do this on your repo. This would completely solve the issue for Dogecoin Core contributors having to worry about any translated documentation at all.

[qlpqlp]

Will do that :)

[patricklodder]

Cool. Originally, there was a .com website that tried to give really high quality information to people. However, due to all the centralization and politics that happened since 2017 - while not much other than politics happened - the maintenance of that website got into disarray. Perhaps, if anyone thinks that more people that speak their language should pay attention to Dogecoin, these people can, on their own, create localized information.

This can be done 100% without interacting with this repository, no matter if it's a translation or original content. If the source English information comes from this repository, and is translated, just respect the license and credit the original work, and all is good. This way, the maintainer of that can 100% focus on the content and its quality, and is much more likely to lead to better results than trying to maintain all of it on this repository.

There really is no need to do it here; which is why I don't understand why you sounded so upset to my suggestion to not support any of the translations at all anymore. Why is that? Isn't it much better to make a whole lot of for-purpose repositories that have their own maintainer than to centralize everything? Not to mention the pain it causes to the topic of this repository: software development.

Perhaps other people that maintain or want to maintain readme translations can weigh in on this: what's the downside of a for-purpose documentation repository or website versus adding translated documentation on this repository?

[qlpqlp]

is there any other trustable source of CORE you can recommend besides this singular trusted repository?
would you and the community in general be somehow happy to have the CORE documentation on core.dogecoin.org or core.dogecoin.com sub domains ?

Yes, I was upset since last year actually mostly because:

• There is more languages besides English already and
• I was happy to contribute as a really crappy dev, but trying to improve
• Pushing away any dev is a bad idea, even if there is no good intentions we should welcome every dev to contribute than the community should be allowed to give their opinion

IMO, there should be a centralized point of trusted Documentation and Software, in this case the central point is here in this repo, we have CORE and Documentation

Luckily there are more projects being build like LibDogecoin, GigaWallet, RadioDoge that I personally believe will maybe revive the Devs and decentralize even more the ecosystem.

Initially there was only CORE, now we also have LibDogecoin as another option that is improving really fast as it should

If I can help somehow organising a little CORE Documentation, great for everyone :)

[qlpqlp]

I'm proposing the creation of a new branch here on CORE called "1.14.7-dev-docs" were as a community we can organize all documentations that later on we could push to a new branch called "main-docs" and use Google Pages to push as a static webpage

https://github.com/dogecoin/dogecoin/tree/3fba0e8b5d7c6cf304593efe66068bcabeb06666

What should be done in your opinion to accomplish this?

[patricklodder]

I disagree with that proposal because branches inherit maintainers and this would automatically either increase the workload for maintainers, or permission people with rights on code that are extremely risky.

Separate concerns. If you want to make a website, make your website. There is no need to do it here.

[qlpqlp]

I disagree with that proposal because branches inherit maintainers and this would automatically either increase the workload for maintainers, or permission people with rights on code that are extremely risky.

Separate concerns. If you want to make a website, make your website. There is no need to do it here.

Would it make sense for you to be on a new Repository on CORE?

I'm trying to contribute to CORE, not for my own personal project, how can I achieve that on improving the Documentation side in your opinion?

[georgeartem]

Agree. Paulo, core is trying to stay focused on executing 1.14.7 release. I thought it was good of Patrick to accommodate your request for pt_PT in a creative way to address added pressure on maintainers with explosion in translations. There is already scope creep in 1.14.7 and these other items would only add to that for the time being. IMO

…

On Thu, Feb 22, 2024 at 12:34 PM Old Dip Tracker ***@***.***> wrote: I disagree with that proposal because branches inherit maintainers and this would automatically either increase the workload for maintainers, or permission people with rights on code that are extremely risky. Separate concerns. If you want to make a website, make your website. There is no need to do it here. — Reply to this email directly, view it on GitHub <#3436 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACZSY44XY4SOVW53B7OPILTYU6TVZAVCNFSM6AAAAABDR3W2UOVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DKNRRGQZDS> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[qlpqlp]

Agree. Paulo, core is trying to stay focused on executing 1.14.7 release. I
thought it was good of Patrick to accommodate your request for pt_PT in a
creative way to address added pressure on maintainers with explosion in
translations. There is already scope creep in 1.14.7 and these other items
would only add to that for the time being. IMO

On Thu, Feb 22, 2024 at 12:34 PM Old Dip Tracker @.***>
wrote:

I disagree with that proposal because branches inherit maintainers and
this would automatically either increase the workload for maintainers, or
permission people with rights on code that are extremely risky.

Separate concerns. If you want to make a website, make your website. There
is no need to do it here.

—
Reply to this email directly, view it on GitHub
#3436 (reply in thread),
or unsubscribe
https://github.com/notifications/unsubscribe-auth/ACZSY44XY4SOVW53B7OPILTYU6TVZAVCNFSM6AAAAABDR3W2UOVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DKNRRGQZDS
.
You are receiving this because you are subscribed to this thread.Message
ID: @.***>

Why not a new Repository inside CORE? to separate things and at the same time organise things that are directly related to CORE?

[patricklodder]

Separation of concerns. I already answered that.

[qlpqlp]

So you don't agree to.have something functional lile this https://twitter.com/inevitable360/status/1761056950047900055?t=FJ5nQkSkEtTaDhBKTLcd1A&s=19https://twitter.com/inevitable360/status/1761056950047900055?t=FJ5nQkSkEtTaDhBKTLcd1A&s=19 on CORE?

How many pei6are needed to vote im favour for the Repo Administrator to consider to approve? what is the ratio consensus of this core GitHub Repo?