Make Documentation Readable Again #3224

New Issue

wvanrensburg · 2024-09-20T17:37:41Z

wvanrensburg commented

2024-09-20 17:37:41 +00:00

Documentation site is pretty hard to find anything. Example, API Reference should literally be the API reference, instead of help articles or feature explanation

sheetjs commented

2024-09-20 17:54:12 +00:00

History

The community has flipped back and forth on this.

Years ago there used to be a single very large markdown file and associated HTML page. Many people loudly complained that the single page was too dense and unreadable, so we moved to a more modern structure with many pages.

Current State

The API reference page currently lists every single function and where the functions are explained in more detail.

Each subpage has details and links to the SheetJS Data Model where relevant. For example, "Reading Files" links to the "VBA and Macros" page when discussing the bookVBA option.

This structure allows us to expand further on certain concepts. Due to limitations in Markdown, we hid many example codeblocks behind details-summary sections. Thanks to the multi-page setup, we can present some of the more relevant sections in a page without cluttering the rest of the documentation.

Improvements

How can we improve the documentation?

Do you think the main discovery issues surround technical details (e.g. how merged cells are represented) or general problem solving (e.g. how to generate CSV rows from a XLSX file)?

If you would like to play with the current structure, https://git.sheetjs.com/sheetjs/docs.sheetjs.com is the documentation source tree.

#### History The community has flipped back and forth on this. Years ago there used to be a single very large markdown file and associated HTML page. Many people loudly complained that the single page was too dense and unreadable, so we moved to a more modern structure with many pages. #### Current State The [API reference page](https://docs.sheetjs.com/docs/api/) currently lists every single function and where the functions are explained in more detail. Each subpage has details and links to the SheetJS Data Model where relevant. For example, ["Reading Files"](https://docs.sheetjs.com/docs/api/parse-options) links to the ["VBA and Macros"](https://docs.sheetjs.com/docs/csf/features/vba) page when discussing the `bookVBA` option. This structure allows us to expand further on certain concepts. Due to limitations in Markdown, we hid many example codeblocks behind details-summary sections. Thanks to the multi-page setup, we can present some of the more relevant sections in a page without cluttering the rest of the documentation. #### Improvements How can we improve the documentation? Do you think the main discovery issues surround technical details (e.g. how merged cells are represented) or general problem solving (e.g. how to generate CSV rows from a XLSX file)? If you would like to play with the current structure, https://git.sheetjs.com/sheetjs/docs.sheetjs.com is the documentation source tree.

Sign in to join this conversation.