[doc] Documentation Improvements: Missing Sections, Confusing Content, and Examples Needed

[tianyi-ge]

Description

This issue summarizes documentation improvements identified from a reader's perspective. The issues are organized into three categories: missing sections, confusing content, and areas needing more examples.

Missing Sections

1. Tutorial/End-to-End Examples

   • Missing practical application examples (distributed training, model inference, etc.)
   • No complete walkthrough of real-world usage scenarios

2. Performance Benchmark Section

   • No performance comparison data (HCCL vs NCCL, YR transport vs regular transport)
   • Missing latency/throughput benchmarks for different operations

3. Migration Guide

   • No guide for migrating from other backends (e.g., NCCL) to HCCL
   • Missing transition path for existing Ray users

4. Version Compatibility Matrix

   • Unclear version correspondence between ray-ascend ↔ Ray ↔ CANN ↔ torch-npu
   • "Same version as ray-ascend" is ambiguous

5. Cluster Deployment Guide

   • Missing multi-node environment setup and configuration
   • No instructions for cluster networking configuration

6. Quickstart with Working Example

   • The current Quick Start only has a pip install command
   • Needs a minimal runnable example to verify installation

Confusing Content

Location	Issue
user_guide/index.md	"Ray: Same version as ray-ascend" — unclear what this means exactly, how version numbers correspond
installation.md	Only provides Docker pull commands, no instructions on how to start container, mount data, or configure devices
hccl_collective.md	"Using Ray's Collective API" example is incomplete, missing code at # Create and setup group...
best_practices.md	"CPU tensors use a packed binary format" — what is this format? Do users need to understand it?
Various pages	Project name inconsistency: "Ray-Ascend" vs "ray-ascend"
installation.md	No explanation of YR_DS_WORKER_HOST/PORT default values or cluster configuration
installation.md	No post-installation verification step or script

Areas Needing More Examples

Feature	Missing Examples
HCCL	Complete examples for allgather, reduce, reducescatter, send/recv, barrier
HCCL	Examples for different reduce operations (PRODUCT, MAX, MIN)
YR Transport	Multi-node transport examples (currently only single machine)
YR Transport	Mixed CPU/NPU tensor transport examples
Combined Usage	Complete application example using both HCCL and YR Transport together

Additional Suggestions

1. Chinese Documentation - Consider providing bilingual (English/Chinese) documentation since many target users are Chinese speakers
2. Glossary - Add more detailed explanations for terms like HCCL, YuanRong, CANN when first mentioned
3. Terminology Consistency - Standardize on either "Ray-Ascend" or "ray-ascend" throughout documentation

Related Link

• User Guide Overview
• Installation Guide
• HCCL Collective Communication
• Best Practices