Some of it is in poor English, a lot of it isn't documented and isn't good to work with in general.
Can't something be setup similar to PHP's docs? Theirs are nice or even CodeIgniter's, I liked working with those.
Maybe start a team effort? People who would like to help build a new set of documentation post in here and probably make a project on Github?
Despite the fact that you are generalizing - I really don't believe that all the docs are bad - you do have a very valid point and we need to address it.
So how can we make sure that we have good and precise documentation? Issues to consider
ReadTheDocs is what we have been using and it works OK. The translation though is lacking seriously and there are issues with switching versions.
There are other document generating applications that we can explore. Ideas? Do we need to build one ourselves? I am positive that if we decide on the latter we can produce a very good piece of software that will serve all of the above needs.
Finally, when do we start? Do we start on 1.x or 2.0?
I already had some contacts from people that do this for a living i.e. write documentation and they have offered help with syntax and grammar etc. so there are people willing to help the project.
Thoughts everyone?
For me I can say that I'm love with the documentation of phalcon fw, I learnt to work with it just in 7 days as well.... and this happens just because the documentation is very nice :) and based on lots of examples etc. :)
Breaking the documentation down into smaller pages would help. It would then be easier to create a table of contents for each page including the subject matter of each page.
It would also help users who want to help with the documentation - we wouldn't have to hunt through hundreds and hundreds of lines of code to find a grammar or spelling mistake.
I liked in the past how each page had a link to edit the documentation page you were currently viewing - it definitely made it easier to suggest improvements.
I'd suggest migrating the documents to a Markdown format. The current language is similar to Markdown, but I've found it dissimilar enough at times to make it difficult to figure out what exactly to do to make my changes.
Finally, I'd suggest starting over with the docs. The number one complaint I see is the documentation. That would lead me do believe that the current documentation is broken (or at least not ideal) a tool to encourage adoption. Don't get me wrong - there is definitely useful information in there. However, I think the documentation needs to be restructured - or at least the structure needs to be re-examined. Trying to hold on to a legacy structure (ie: the current documentation) will only hamper the necessary changes that need to happen. Certainly the current content can be used, but it may need to be chopped up and re-arranged to make it fit.
As for what version? I'd say the version to next be released whenever this project gets going. If v2 is 8 months away, make the documentation for that version - there's no sense building documentation for a version that will be obselete 1 month after the documentation gets written.
You definitely covered what I wanted to say @quasipickle - good job!
Just touching back onto this, I think all the sections need to be displayed in a navigation bar on the left at all times with an accordian sort of layout. Similar to: https://docs.syncthing.net/index.html which also uses Sphinx.
Here is an example of the poor documentation. On the page https://docs.phalcon.io/en/latest/reference/tutorial-rest.html
The page has, "Then, in the index.php file we create the following:" after which it has the index. Seemingly for no apparent reason, the acutal routes follow where it says, "Now we will create the routes as we defined above:" followed by some routing info but still including all of the code from the prior snip. Why not just show the whole file from the start? Nowhere does it say, "now add this to what we just created above where it says, '// Define the routes here'." It's like the author created two steps for no aparent reason.
Then under creating the model and after providing the code for the model, it says, "Now we must set up a connection to be used by this model and load it within our app." It then follows that with a block of code but there is no indication of WHERE to put that code. The rest of the so-called tutorial just throws more code at you but never tells you were to place it.
For most of the rest of the world, a tutorial provides all the information to complete a tutorial. This tutorial comes far short of that. IOW, after TRYING to follow what little instruction there is, the tutorial doesn't work at all. How is anyone supposed to learn anything if the tutorials aren't clear and end up not working?
