-
Notifications
You must be signed in to change notification settings - Fork 0
Description
After talking to some external WoC users who asked me for help because they struggled with using and understanding how WoC works, they found it very difficult to understand which maps exist, what the abbreviations stand for, and how to figure out which maps exist. Audris also thinks that it might be a good idea to have all of that documented in an easy to access way.
@loconous Could you please create an overview of the following pieces of information and place this very prominently in the documentation?
- Glossary: a very short description of every character / sequence of characters that is used in any of the current or previous maps? There are already such glossaries in the tutorial, but they are hard to find and mostly outdated (as already previously indicated in Outdated parts of the tutorial #2 and Outdated parts of python-woc #3). It would be good to have one glossary that contains all characters. (For example, some maps use l for programming language, but it is almost impossible from the current tutorial to figure out what l stands for.)
- Overview of the existing maps: While some map names are self-explanatory, others are not (e.g., c2dat might contain more columns than just the four c d a t). For maps that have an unexpected output, it would be helpful to have a short description of the output columns. Same holds for maps that rely on any undocumented assumptions.
- A quick overview of random access maps vs. regular access maps - what are their differences, when to use what, etc.
- How to figure out which maps exist (e.g., "ls /da?_data/...") together with the information that each map might be split into multiple chunks and a very short example of how to access them via zcat.
- An overview of the versions. There is already a page on versions, but it contains dozens of irrelevant lines of code and stops at describing version U. Just a small table would already be helpful, having the following columns: Version Identifier, Time of Data Extraction (roughly, month year), additional comment (e.g., work in progress for current version; or which maps have disappeared with a new version because if design decisions and their replacements, etc.).
Having a small page that contains the five pieces of information stated above might be very helpful for new users of WoC to obtain an overview of how the data looks like and how to access it. This can be even more important than the actual tutorials - to get an overview of the infrastructure before doing the hands-on tutorial.