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.
Is your feature request related to a problem? Please describe.
The documentation consists of three parts:
Each part has significant shortcomings: The language tour is probably
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:
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:
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.