search

NetAppDocs / data-infrastructure-insights

Data Infrastructure Insights Documentation (formerly Cloud Insights)
https://docs.netapp.com/us-en/data-infrastructure-insights/
5 stars 18 forks source link

another table that isn't a table and that is breaking translation #2647

Open ntap-bmegan opened 4 weeks ago

ntap-bmegan commented 4 weeks ago

Summary

  1. Do not manually create a TOC with links. That's what the right sidebar is for.
  2. If you have to put "back to top" links in an article, the article is too long and needs to be split into separate articles.
  3. Do not use single-column tables ever for any reason.
  4. We do not support :toc-title:, :description:, toc::[], :toclevels: and possibly other notation that is present that I haven't found in the 10k-plus lines of notation.

This page causes my browser to hang, but right now I care more that it causes our translation system to come to a crawling halt. Specifically, it's failing at reference_data_collector_support_matrix.adoc line 10262)

image

This article cannot continue to exist in this form.

Reference: https://github.com/NetAppDocs/oncommand-insight

Public issues must not contain sensitive information

ntap-bmegan commented 4 weeks ago

Edit to add page link: https://docs.netapp.com/us-en/cloudinsights/reference_data_collector_support_matrix.html

ntap-bmegan commented 4 weeks ago

At a minimum, the translation problem needs to be resolved by then next push to production or thurs 31 oct 2024, whichever comes first, or we will remove your merge permissions until a suitable PR is opened in the internal repo.

jenatnetapp commented 4 weeks ago

@netapp-alavoie, NetAppDocs authors are responsible for understanding and complying with our authoring and content standards. Thank you for your attention to this.

netapp-alavoie commented 4 weeks ago

I'm working to resolve the four points noted. Once these are resolved, can we check that the translation problem is fixed?

Understood.

ntap-bmegan commented 4 weeks ago

The immediate focus if you want to prioritize is the "table" starting at the linked code line above. That's what is breaking translation.

netapp-alavoie commented 4 weeks ago

I'll move that table to a bulleted list, along with the few other single-column tables in the page. Also removing the "toc" likes and the "Top|back to top" links.

I'll also refresh my understanding of these areas. Can you point me to the content standards that talk about them?

ntap-bmegan commented 3 weeks ago

Our developer has found more files that are also breaking translation. I've combined the list for easy reference. The original one reported above is first. Also, since he gave line ranges for the new ones, I went back and got the range for the first.

  1. https://github.com/NetAppDocs/cloudinsights/blob/main/reference_data_collector_support_matrix.adoc?plain=1#L10254-L10338
  2. https://github.com/NetAppDocs/cloudinsights/blob/main/task_add_collector_svm.adoc?plain=1#L341-L376
  3. https://github.com/NetAppDocs/cloudinsights/blob/main/task_add_collector_svm.adoc?plain=1#L385-L400
  4. https://github.com/NetAppDocs/cloudinsights/blob/main/task_config_telegraf_elasticsearch.adoc?plain=1#L100-L194
  5. https://github.com/NetAppDocs/cloudinsights/blob/main/task_config_telegraf_hadoop.adoc?plain=1#L369-L498
  6. https://github.com/NetAppDocs/cloudinsights/blob/main/task_config_telegraf_kafka.adoc?plain=1#L79-L227

As requested

Everything in NetApp Docs Help and in Content Standards is relevant. I've pulled a few references for you to start with.

Supported and unsupported notation

Supported Anything that is documented in NetApp Docs Help that is not explicitly characterized as prohibited is supported to the extent documented.

Supported conventions, structures, notation, and practices are considered in all process, design, and feature updates. While it might be necessary to withdraw support for something, decisions to do so evaluate the impact on existing content.

Prohibited Certain conventions, structures, notation, and practices are prohibited because they interfere with publishing, complicate maintenance and support, or violate content standards. These items are explicitly identified. For example, HTML passthrough blocks and AsciiDoc checklists are explicitly prohibited.

In addition to prohibited notation, there are limits on object names and repository structure that you should be aware of.

Not supported If nothing is said about it, it's not supported. This is a sort of grey area in the middle. We don't officially support it, but we haven't prohibited it - yet. It might work end to end, it might not. If it was working and stops working, we might fix it, we might not.

If you want to use notation and its status is not clear, you should open a discussion to ask about the notation. It's possible that the question just hasn't come up. If you ask, admins and the content standards team can evaluate it proactively.

Content standard for article length and max headings

Tables: content standard and syntax.

ntap-bmegan commented 3 weeks ago

@netapp-alavoie - Sorry, forgot to mention. Can you tag @dmajones and @ntap-bmegan in the public PR so that we can monitor the translation activity.

ntap-bmegan commented 3 weeks ago

@netapp-alavoie - When will this be resolved? It is urgent, as we cannot deploy the Portuguese site.

netapp-alavoie commented 3 weeks ago

i believe I have the original table fixed and deployed. I'll try to have the other five files fixed today.

netapp-alavoie commented 3 weeks ago

I captured these in a doc bug for me to work on. I'll tackle in two phases:

  1. Remove the offending table or table sections, to allow translation to proceed. (immediate)
  2. Fix the table issues and re-implement them, and ensure translation still succeeds. (after)
netapp-alavoie commented 3 weeks ago

It was not immediately apparent to me what the issue is with the SVM page, other than the table possibly making the page too long. Is that the case with the two flags above for this page?

I've split the "Troubleshooting" away from the main page, as a start. If the problem is that the table itself is too long, would splitting that table help?

ntap-bmegan commented 3 weeks ago

The problems are all too-long translation segments.

A table cell is a single translation segment unless the contents are divided into paragraphs (signaled by a blank line) or list entries. It might be that each sentence is a segment, but that's not pertinent here. As I said in the other issue about a substantially similar table, replace the table with a list.

I've not looked at the others. The list came from the developer that we had to call in to debug the failure.

netapp-alavoie commented 3 weeks ago

I'll look at it in that context and see if I can figure out how to change it. These tables have been around for a while...have they always broken translation, or is it something around the new Portugese rollout effort? Just curious.

ntap-bmegan commented 3 weeks ago

That looks like it did the trick.

image

netapp-alavoie commented 3 weeks ago

Cool beans. :)

For the three pages where I removed the long column, I'll check with PM here on whether we need to include the granularity represented by that column. If not, I'll consider those resolved. If so, I'll see about re-working that information to avoid the extra tall column.

For the SVM/Troubleshooting page, it looks like we're good for now, but it's a "my car isn't making the noise now but I'm not convinced anything got fixed" situation, so I'll look more into re-working the information on the page, if possible.

For the matrix page, I need to take the changes I made back to the acquisition team, so they can modify their code which provides me with the source file when an update is needed. I have a separate bug tracking that.

Are there other issues we want to track or think about here, or should we consider this ticket resolved?

ntap-bmegan commented 3 weeks ago

We will be adding Lipi checks to alert authors of potential segmentation problems, but I don't know when they'll be available.