search

AdguardTeam / KnowledgeBaseDNS

AdGuard DNS knowledge base
78 stars 94 forks source link

Migrate AdGuard Home wiki to this Knowledge Base #120

Open ameshkov opened 1 year ago

ameshkov commented 1 year ago

AdGuard Home Wiki markdown files available by cloning the repo: https://github.com/AdguardTeam/AdGuardHome.wiki.git

The problem with the Github Wiki is that it does not support localization unlike the DNS knowledge base.

As for why keeping AG DNS and AdGuard Home together, I suppose there are many common topics and thus it makes sense to keep them together.

The task itself should be done in several smaller pull requests.

Please structure the process the following way:

  1. Create a branch named adguardhome.
  2. Create new branches from that branch.
  3. Create pull requests to that branch.
  4. Once we have all content finalized in that branch, we'll create a new pull request to the master branch.

Please ask @ainar-g help and add them to every pull request.

A few notes about the work itself:

  1. Add a new section to the knowledge base and call it "AdGuard Home".
  2. AdGuard Home wiki often has "internal" manually written tables of contents. We don't need them as Docusaurus builds them automatically.
  3. Do not follow the same markdown style when migrating the content, rely on auto-beautify by VS code. Sorry @ainar-g, the reason for that is that I am almost sure that Crowdin won't play well with the guidelines you're using now as Crowdin will ruin it completely when re-importing the content.

Once this work is finished and the KB is live, we'll start changing the existing AdGuard Home wiki and funnel people to the new location.

ainar-g commented 1 year ago

I'm not against this idea—and, if anything, I'm happy to store this documentation in the place where most public AdGuard documentation is stores—but there are a few issues I'd like to resolve before going all-in with Crowdin here.

  1. There are a few articles that really need some love, and I would rather not import them in their current state. That includes but isn't limited to:

    1. The “Configuration” page, which really needs to be split into two: configuration recommendations and a description of the configuration file schema, à la the one AdGuard DNS has.

    2. The “FAQ” page needs some stuff added.

    3. Quite a few more, see the Documentation milestone.

  2. The Markdown flavour used by the K.B. is different from the GitHub Wiki one. In particular, the following features are used in our Wiki that may or may not have equivalents in K.B.:

    1. Tables, see the “Platforms” page. This is likely supported.

    2. Empty <a> elements for legacy anchors. Likely isn't supported.

    3. <br/> elements for forced hard line break. Likely isn't supported.

    4. Centering of images using align="center". Likely isn't necessary.

  3. Regarding the Crowdin translations, it seems like Crowdin's support for Markdown is finicky, as you've mentioned. We'd need to define a set of dos and don'ts in the form of a guideline document, similar to the one we have for the AdGuard Go Team. Especially when it comes to things like paragraphs within list items. No one autoformatter will likely be able to take all of Crowdin's weirdnesses into account, and I'm not buying your VSCode propaganda 😁.

  4. The Content Team should be instructed to not merge anything until one of us approves the changes to make sure that the documentation stays correct.

  5. Finally, some parts of the task will have to wait until the AdGuard Go Team has time to do this right, obviously.