pomsky-lang
Rework the documentation
Is your feature request related to a problem? Please describe.
The documentation consists of three parts:
- Language tour
- Reference
- Examples
Each part has significant shortcomings: The language tour is probably
- too hard to understand for complete beginners who aren't familiar with regular expressions
- too detailed for people who know regular expressions and just want to get to know the syntax
The reference is meant as a complete specification of Pomsky's syntax and expected behavior. However, it currently only contains the formal grammar, the list of Unicode properties and built-in variables, which is not sufficient. It also contains a page about security and a comparison with other projects, which arguably don't belong there.
The examples are useful, but there aren't that many. Furthermore, it would be better to have real-world examples, which are used in actual projects.
Describe the solution you'd like
The documentation should consist of 5 parts:
- Get started
- Learn Pomsky from the ground up
- Examples
- Reference
- Appendix
Explanation
Get started
Here, the user is introduced to Pomsky with a small example and learns how to install the CLI and the VSCode extension, or use the playground. They are informed how to enable Unicode support and, if the user wants to use Pomsky with JavaScript, how to use unplugin-pomsky.
The user is then asked if they're already familiar with regular expressions. If they are, they're recommended to continue with the cheat sheet on the next page. If not, a link takes them to the next part, "Learn Pomsky from the ground up".
Learn Pomsky from the ground up
This is a tutorial meant for complete beginners. It is structured in the same way as the language tour, but each concept is explained in more detail, and more advanced concepts are skipped. The tutorial includes many examples, which can be either modified and run directly, or contain a link to the playground.
Examples
This part is mostly fine, but should be extended with more examples.
Reference
The reference is rewritten from scratch. Every language construct gets its own page including the following information:
- Summary
- Formal grammar
- Short example
- Support in different regex flavors
- Detailed explanation of the behavior
- Compilation
- Pitfalls and security concerns
- Changelog of the feature
Appendix
This part contains the comparison with other projects and the page about security.
How to contribute
If you are a native English speaker or have excellent English skills, you can help writing the new documentation in the website repository.
