Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate AdGuard Home wiki to this Knowledge Base #120

Open
ameshkov opened this issue Jul 6, 2023 · 1 comment
Open

Migrate AdGuard Home wiki to this Knowledge Base #120

ameshkov opened this issue Jul 6, 2023 · 1 comment
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@ameshkov
Copy link
Member

ameshkov commented Jul 6, 2023

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.

@ameshkov ameshkov added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 6, 2023
@ameshkov ameshkov changed the title Migrate AdGuard Home knowledge base to this KB Migrate AdGuard Home wiki to this Knowledge Base Jul 6, 2023
@ainar-g
Copy link
Contributor

ainar-g commented Jul 6, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants