First of all, it takes a large amount of time to write the documentation, which is why even after a year when I started it, it's still not complete. While I can get everything but the X format documentation complete soon, there will always be something to add, to refine... and that just takes time, and more of time.
Second of all, the way it is written is catastrophic, the formatting is not very attractive to read, and you might find the information you are looking for only after reading through things that possibly aren't of interest to you. I have tried to create a specification in many areas, documenting the syntax and exact behavior, and while I think this is necessary, it often makes it more cumbersome to read and get the basics.
In the long run, I think that writing a good documentation will simply not be possible for me alone, because it takes time to write and time to verify.
As such, if there are people who have the knowledge and experience, and are willing to assist me, it might be worth considering to convert the Developing for openBVE pages into a wiki. This way, multiple users could work on completing the documentation, and more importantly, to rewrite it into something easier to work with.
Of course, this would require first to identify what the good and bad aspects of the current documentation are, and to come to a conclusion on how it should be done. As a starting point, I think there should be:
- A "getting started" tutorial, which only addresses the most basic points, skipping unnecessary details such as the precise syntax, unimportant commands, etc..
- A complete reference including all commands and their precise behavior and interactions.
- Precise syntax and other details that are necessary if someone wanted to implement the format without having to reverse-engineer.
- Images... images... and more images. Currently, images/illustrations are what are missing in many cases, but would greatly make things which are difficult to explain easier to comprehend.
