More detailed info per concept

[cafce25]

What I propose

For each structure there should be a documentation page that explains every category in more detail.

Why this is a good idea

It can be hard to correctly implement a structure file cause it is not always clear what a category is about just from the short category header alone.
This would make it easier to find it out and thus it would help to keep implementations across languages more consistent

Possible implementation

# Lists, Arrays, and Hashed Lists
Data structures that keep multiple objects together.
<dl>
  <dt>List</dt>
  <dd>A data structure that keeps multiple elements often of the same type</dd>
  ...
<dl>

## Ordered Mutable Lists
Concepts for a mutable list that keeps the elements put into it in the same order.
i.e `print OrderedList(5, 6, 3, 4) => "[5, 6, 3, 4]"`
### Examples
- Python: `list`
- Haskell: `List`

## Sorted Mutable Lists
Concepts for a mutable list that keeps the elements put into it sorted (by value or something similar).
i.e. `print SortedList(5, 6, 3, 4) => "[3, 4, 5, 6]"`
### Examples
- C#: `SortedList`

## More Categories ...

[cafce25]

I do think this should be broken down into an issue for each structure but wanted to have input from you @geekygirlsarah first before I create a bunch of issues.
If you like that I'd create an Issue per structure and we could keep this around as a tracking issue for the others.

[geekygirlsarah]

Hmm, I do like this, but actually thought this was an issue on CT's site, so I was pondering how descriptions could be added in meta files for display on the site (but also included in the file when people implement them in text editors). So this might be a good way to do it but not have to consult the docs. (Also the success rate of people reliably reading docs before submitting things isn't always great...)

Thoughts on this?

[cafce25]

You're right, inline documentation would be great for this. On the other hand it's documentation and thus belongs here too. I'm thinking maybe we can have the best of both worlds, add the documentation to the meta/* files but then generate corresponding pages here. Maybe a gh-action can take the part of updating docs whenever the meta files are changed in this scenario.

[monkeywithacupcake]

Commenting to say that I love this idea. People may read the name of the concept and not be entirely sure what that means in the language that they know how to use. Especially given that some words become verbs in languages that are not the same thing as the general purpose of that word.

[geekygirlsarah]

Oh gosh, the cross-repo commits will be a bit wild, but I suppose it could work if someone felt up to that. I figure stuff that's documented on the main site with regards to language stuff isn't really cross-posted to the docs, which is more about how to use and develop on the site. So since this would be language-specific, it should go in CT and not in the docs.

[monkeywithacupcake]

*could the docs become part of the main repo? (I assume there is a solid reason to split them, so I don't want to presume that combining is the right thing to do)

[geekygirlsarah]

I have thought about this. They're two separate build processes. (ct.us is Heroku, docs is Netlify.) While they could be merged and set up to have separate build processes, that's probably a thing only I can do due to needing access to the accounts, and my time is getting focused on some more important things. Not ruling out the possibility of the documentation that can go in both places, but really for now I think having it in the meta files is easiest and most logical.

[cafce25]

Ok then I'm gonna leave this open cause we still should link to ct user docs at the least,
but I'll also create an issue over at the main repo to add the docs.

[geekygirlsarah]

I'm fine leaving this open as we think on it more.