refactor/docs 2

[leo-gan]

PR Description:

Documentation Restructure & Theory Content Expansion

Summary

Restructures documentation site architecture and adds comprehensive theory perspectives on serialization.

Changes

Documentation Architecture:

• Moved theory content to dedicated docs/theory/ directory with new index
• Renamed test_data_design.md → test_data_configuration.md for clarity
• Renamed languages-overview.md → serialization_categories.md
• Updated all internal cross-references

New Theory Content:

• data_science_perspective.md - Statistical analysis approach to serializer evaluation
• engineer_perspective.md - Text vs binary vs schema-driven format trade-offs with historical context
• historical_perspective.md - Evolution of serialization formats and key contributors

Updates:

• Regenerated benchmark logs with latest run data
• Updated python_tested_serializers.md with additional serializer details
• Revised MkDocs navigation to reflect new structure

Testing

• Full benchmark suite executed (100 reps, all serializers) - results verified
• Documentation builds successfully with MkDocs
• All internal links validated

[gemini-code-assist]

Code Review

This pull request restructures the documentation and adds comprehensive historical, engineering, and data science perspectives on serialization, while updating serializer references for C# and Python. The review feedback identifies several issues in the new content, such as accessibility concerns from using images for text, factual errors, and broken citations. Suggestions were also made to fix code block formatting, resolve a missing import in a Python example, and consolidate the new perspective documents to reduce redundancy and maintain consistent spelling and citation styles.

[gemini-code-assist]

The explanation for 'Partially Tested Serializers' could be more precise. Stating that some are tested with specific data types is good, but it would be even clearer to mention that they might fail or be explicitly excluded from tests with certain data types (like those with circular references or requiring specific schema attributes), as detailed in the table below.

[gemini-code-assist]

This section contains a couple of issues:

• The citation [26] on line 120 is broken, as there is no corresponding entry in the references section.
• On line 122, Brian Behlendorf is incorrectly listed as a YAML contributor. He is primarily known for his work on the Apache Web Server. The previous line correctly identifies the main YAML contributors.

[gemini-code-assist]

The citation style in this document is inconsistent with the other new documents and is hard to read. Citations are appended directly to words (e.g., devices.1), which can be confusing.

For better readability and consistency, please:

1. Use the [1] format for citations, as seen in data_science_perspective.md.
2. Add a space before the citation (e.g., devices [1]).

This formatting issue appears throughout the document.

[gemini-code-assist]

There appears to be significant content overlap between the three new 'perspective' documents (historical_perspective.md, data_science_perspective.md, engineer_perspective.md). The quality also varies, with data_science_perspective.md being the most comprehensive and polished, while the others contain formatting issues and errors.

Consider consolidating these into a single, high-quality document to avoid redundancy and provide a more focused reading experience for users. If different perspectives are desired, it might be better to structure them as sections within one file.