KhronosGroup / KhronosGroup/SYCL_Reference

"Devices" Information Descriptors format

Open
#75 9 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
31
Forks
26
PR merge metrics
No merged PRs in 30d

Description

We faced some problems with updating the Information Descriptors section for sycl::device. We have three options for how information can be formatted there:

1. In **table** like we did in "Platforms" and "Contexts":
![image](https://github.com/KhronosGroup/SYCL_Reference/assets/122783909/d270fdf4-6ba5-473a-9c80-58eedbda853d)

[KHRGA-57_RC_devices](https://github.com/imvucic/SYCL_Reference/tree/KHRGA-57_RC_devices) branch

Pros: Consistency, description added, easy-to-understand structure
Cons: Some names are so long (even if you try to shrink them) that the table becomes enormously wide (still looking for a solution), so the contents will cover it partially. The page becomes very big.

2. Using subsections:
![image](https://github.com/KhronosGroup/SYCL_Reference/assets/122783909/4940cedf-0d67-4e97-9af1-040513ca9112)

[KHRGA-57_RC_devices_no_table](https://github.com/imvucic/SYCL_Reference/tree/KHRGA-57_RC_devices_no_table) branch

Pros: Description added, full names without removing scopes, easy-to-understand structure
Cons: For consistency, updating "Platforms" and "Contexts" will be necessary. The page becomes very big

3. Leaving the link to the spec, like it was previously:
![image](https://github.com/KhronosGroup/SYCL_Reference/assets/122783909/0c5ed106-fd68-417b-b2ad-f865e6dd32b3)

Pros: The page will become more concise
Cons: No description will be added for "Information Descriptors"

Which option is better? Or are there any other proposals?

Contributor guide

No contributing guide indexed for this repository

Research direction

Compare the KHRGA-57_RC_devices and KHRGA-57_RC_devices_no_table branches with the current "Devices", "Platforms", and "Contexts" Information Descriptors sections. Review the discussion and decide on a format or proposal; the work is done when the project has a clear decision and the affected reference documentation is updated consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.