Hi, I would like to create an global index for the Crystal lang documenation.
The idea is to provide a web page (or a frame) pointing to the official doc, displaying the complete content of all the pages of the crystal documentation, in the shape one tree structure (global table of contents) with clickable links similar to e.g. the index for the Python doc: The Python Standard Library — Python 3.9.2 documentation
I am interested to do this for my own benefit, but I wouldn’t mind sharing it publicly in the shape of a Gitbulb web page.
In order to achieve this, I could navigate the existing Crystal documentation site recursively, or make a local copy (to scan the doc from the file system) or possibly download a zipped version of a doc if it is available.
Home - Crystal is indeed an index with a tree structure, but points only to the “language reference” (specificatiin of the classes, methods, etc). It is a good reference, but not teaching material for beginners.
On the other hand, the didactic part of the documentation which explains the concepts of the language and their use, often using snippets to illustrate, is located in a collection of subdirectories located under the /syntax_and_semantics/ directory and, although they are all linked together (allowing to navigate individually from one isolated item to the next), there does not seem to be a global common index on one single page pointing all the html documents contained in the /syntax_and_semantics/ folder ( which would allow direct access rather Thant sequential access).
I don’t really get what you’re aming at. I understand you basically want a sitemap of GitHub - crystal-lang/crystal-book: Crystal docs at https://crystal-lang.org/reference. It happens to be at Crystal although it’s not reachable from the website navigation. We could add a link to that, but I’m not sure how useful it really is compared to the already existing navigation menu and search feature.
This page provides me with a direct (random) access to the topics I am looking for regarding a given subject, without having to navigate from subject-to-subject via the doc section of the links. The links provided in the docs are more like a linked list, this is more like map or dictionary.
In other words, the links provided in the home pages are more like a manual which one reads sequentially, chapter by chapter, whereas this is more like an index or a table of contents which allows one to jump straight to a given topic of said manual.
But isn’t the search feature much better suited at this? It even makes topics available that don’t appear in an individual page title.
The landing page and sidebar menu should be sufficient to give a high-level overview. The sitemap page sits somewhere in between sidebar menu and search.
Sure, it’s already available (even if just a byproduct) and we could just add a link to it. But I don’t really see much benefit. Especially considering that it would be incomplete in that sense that it only includes topics in crystal-book. API docs and installation instructions for example don’t appear.
That actually looks like a pretty typical project readme. I don’t understand how that relates to a sitemap of the Crystal documentation.
It might really help if you could just make an example to show what you mean.
I will say with the old book you could kinda just scan the list and navigate to things at will, like you can with the summary page. The new book navigation has the collapsing sections which makes navigating like that a bit harder.
That said, I have been using search more than before and have been able to pretty easily find what I was looking for.
Perhaps, part of the problem (subjectively) is that I have used most of the major programming languages in the past, except for Ruby, therefore the Crystal doc seems a bit dodgy subjectively to me.
These “collapsing sections”, I think, do not help a Crystal beginner (like me) to have a bird’s eye view of the language (unlike Python or Node or Golang or Rust).