Convert /learn folder to Markdown (es)

[queengooborg]

This PR converts the /learn folder to Markdown for the Spanish locale, using my fork of the mdn-markdown repository.

Disclaimer: I am an English content writer rather than a localization expert, and as such I strive to keep my changes purely editorial.

[Graywolf9]

Hi! @queengooborg thank you so much for your PRs. I assume that it is by the automate conversor for html to md, as we said on the matrix channel at least in es docs we are goin to try put an attribute indicating the date from the html file this is due to the html content is outdated about 2-5 years and is and indicator to us to know and control them. If this don't matter to you I'm going to edit the PRs to add this info and keep the translation update control

[queengooborg]

Ah I see, thanks for the head's up about the new frontmatter key! Yes, these changes are almost all automated with the conversion script (specifically, my fork of it), with additional manual tweaks to convert HTML the script doesn't know how to handle.

[Graywolf9]

Thanks to you! I'm going to start reviewing and adding that info to all your modified files in the last PRs

[Graywolf9]

Hi! @queengooborg I added the attribute htmlDate to identify the outdated content, also we usually avoid doing big PRs to avoid and control this kind of risks #7436

Did you check if that error did't happend in this or others PRs? if yes, how?

Thank you so much for your time

[queengooborg]

I added the attribute htmlDate to identify the outdated content

Thank you! I'll tweak the Markdown conversion script to automatically add this property in as well. 👍

we usually avoid doing big PRs to avoid and control this kind of risks #7436

Makes sense -- over on the English content side, and for BCD (my main project), larger PRs are preferred when they're scripted changes, so that's what I'm accustomed to doing. I'm hoping that by the time I'm finished with the Spanish locale, the script will handle everything and no manual review will be required any longer!

Did you check if that error did't happend in this or others PRs? if yes, how?

I did -- I checked out a commit earlier to my prior PRs' merge commits and searched for "Quick_links" in all the affected files. Luckily, the Glossary folder was the only one that had those sections in them, I'm guessing that the macros handle most of the sidebar stuff.

Thank you so much for your time

Of course, always happy to help out wherever I can!

[queengooborg]

In regards to the htmlDate frontmatter key, it looks like you've formatted it as YYYYDDMM, but shouldn't it use the ISO standard (that is, YYYY-MM-DD)? This would make it a lot easier for everyone to identify the date internationally.

Also, is there an issue or discussion about this frontmatter key somewhere here or on mdn-community?

[Graywolf9]

Sorry I'll change it, thank you

We talk about this key in the matrix chat with @schalkneethling only for the es locale due to it's recently unfreezed and its old content, also schalkneethling add a note for the past event and talk about that spanish is a special situation, and I already said that the es team are working on tools for keep having the track of those big amount of outdate files and in the event has a spreadsheet for do this conversion by document and mention that you have to do a manual check for each file

NOTE: When looking for documents to convert, have a look on the repository https://github.com/mdn/translated-content for documents that are not too old. Start from the most recently touched documents and work backwards from there.

Once the convertion completes, view the page in your browser by going to http://localhost:5042/ for example http://localhost:5042/es/docs/Mozilla/Add-ons/WebExtensions/Prerequisites

Find the file that was converted and just double check that the Markdown looks good. Do not be to concerned here, if the page seems to render correctly in the browser, you can still open the pull request. If there is anything that can be improved with the Markdown, the reviewer will let you know as part of the pull request review process

https://pad.mozilla.org/p/mdn-markdown-hack-day

About larger PRs, you can find in various sites that the recomendation is small PRs and emphasizes in always do a manual review, here's an example

If a pull request becomes too large or contains too many unrelated changes, it becomes too difficult to review

https://github.com/mdn/content/blob/main/README.md#pull-request-etiquette

Thank you so much again

EDIT: for future info the bot fails due the amount of files https://github.com/mdn/translated-content/runs/7735327304?check_suite_focus=true

[queengooborg]

About larger PRs, you can find in various sites that the recomendation is small PRs and emphasizes in always do a manual review

That makes sense -- I think that larger PRs have been preferred for me because I'm an MDN and OWD contractor (and have write access to the repos accordingly), so I'm a much more trustworthy user -- I definitely wouldn't want some random user submitting a larger PR, even if it did mostly come from a (trustworthy) script. ;P I'm happy to split this PR up into smaller chunks to make reviews easier, by the way!

We talk about this key in the matrix chat with @schalkneethling only for the es locale due to it's recently unfreezed and its old content, also schalkneethling add a note for the past event and talk about that spanish is a special situation, and I already said that the es team are working on tools for keep having the track of those big amount of outdate files and in the event has a spreadsheet for do this conversion by document and mention that you have to do a manual check for each file

Forgive me for asking about matters that have already been discussed and whatnot, I'm just going by what I have been told to do in similar scenarios for other parts of MDN (I'm fairly new to the MDN localization community)!

[Graywolf9]

Everything its ok, we are almost new too, it's only that spanish has a lot of work and doing it well and step by step help us to offer better content to the readers and this is only for the es-team, I don't know how each localization team works, but each team are for help to everyone :)

I'll just do some reviews and add the key

Thank you!

[Graywolf9]

Hi! @queengooborg I hope you're having a great day, I'm still reviewing the files and notice this piece of code deleted from a file and just want to know how's the code to remove it to ensure not repeat errors like #7436.

Note: I think the deletion of that code is OK, I just want to guarantee that other files don't have an error due to the automation.

Also notice that there's an error formating "Notes" with more than one line

Code:

<div class="originaldocinfo">
<h3 id="Informaci.C3.B3n_del_Documento_Original" name="Informaci.C3.B3n_del_Documento_Original"> Información del Documento Original </h3>
<ul><li> Autor: Bob Clary
</li><li> Fecha de la última modificación: 20 Feb 2003
</li></ul>
</div>
{{ languages( { "en": "en/Properly_Configuring_Server_MIME_Types" } ) }}

[Graywolf9]

About all the mentioned above we think the best it's going to be close this kind of big PRs due to the large list of files and lack of reviewing before making it. I reviewed some random files and notice various inconsistencies and it's going to be so hard to our team to review the integrity of the entire PR.

Thank you so much for all your time and hope in future PRs with mayor changes we can have a manual reviews before doing the PR

[queengooborg]

The section that was removed was basically original wiki information -- since that is all in the _wikihistory.json file, there's no need for it to be in the Markdown itself!

By the way, I spoke to Schalk about the htmlDate frontmatter key to confirm the story, and we are NOT good to go on adding it yet. Before it is added to documents, we need to open a discussion and plan out exactly how the key will function, what its name will be, etc.

[Graywolf9]

Then we still needing to have some way to control the 2-5 years content outdated before doing this big changes without human review

[queengooborg]

Of course, I'm not saying that we shouldn't add something to make it clear how outdated a converted HTML document is -- but let's make sure that everyone, including other localization teams and MDN engineers, are all on the same page and in agreement about how to do it first!

Would you like to open a discussion in the mdn-community about the frontmatter key to get planning going? Happy to open it as well!

[Graywolf9]

Thank you so much, I opened it, hope to get that to start converting es files into md and keep the work of the es team under control

mdn/mdn-community#173

[queengooborg]

I've also reopened this PR and marked it as a draft instead (I didn't see it was closed until just now) -- I'm happy to split this off into smaller bits to make it easier to review, but let's leave this open as a breakdown PR to show what is affected and better represent my intent of what files I'm handling, so that others don't perform duplicate work. :)

[Graywolf9]

if you can split this it's going to be great!

Also as I notice the script don't put correctly the "Note:" format when have more than one line (I don't know if have the same error on other kind of notes) and it's going to be helpfull to have a mention of deleted sections in case that apply.

Thank you so much and sorry about the inconvenients, I'm very glad to talk and proceed with this