Add documentation

[skoop]

The current documentation is a bit... limited.

I've just started working with Prophecy today and I've found it very limited. Since nothing else exists, I'm considering spending some time in the coming months as I get to know Prophecy to create some documentation for it. So I guess this issue is the issue for discussing that documentation.

[skoop]

First question I had (on Twitter): Any documentation system/format that is requested from the project?

[aik099]

It depends on where it will be hosted. I personally like ReadTheDocs and there RST format is used. If the documentation will be hosted on GitHub Wiki, then Markdown is fine.

@everzet , any idea on this?

[skoop]

RST format is very nice, Markdown is fine as well for me. ReadTheDocs is (imho) more accessible than Github wiki, but that means another site to visit. I personally don't have a specific preference, so I'll be glad to do whatever people are interested in

[ciaranmcnulty]

I'm sure we'd be happy to point prophecy.phpspec.net to it

[stof]

I see 2 different possibilities:

• a doc written in markdown and displayed by github itself
• a doc written in rST and displayed on readthedocs

In any case, the doc should be stored in a docs folder in the repo (allowing it to be versioned alongside the code and updated in PRs adding new features). Github wikis are a bad idea (no PR to update them, no version etc...)

[stof]

@skoop let's go for rST then. It gives a bit more power than Markdown

[skoop]

OK, rST it is. I will write docs in rST in the docs/ folder, and whatever happens after that is up to you. I'm not promising a timeline yet though, I'm just getting to know Prophecy, it might take a bit of time before I can come up with useful docs.

[aik099]

You might want to look at how other ReadTheDocs documentations are formed to see where to place the files and what ReadTheDocs configuration file to create. The Behat (or any other) documentation can serve as good example.

The https://github.com/minkphp/phpunit-mink/tree/master/docs can be used to boostrap a new documentation.

[jakzal]

You might also look into phpspec docs.

[everzet]

I'm all for documentation, but let's do one step at a time. Before going into configuring RTD and fiddling with templates, we could already start writing docs and putting them into docs/ folder. That will give a good starting point for people to have some docs. When that happens we can think about making these docs beautiful and available somewhere else.

[tyteen4a03]

Bump - I was trying to find the API documentation online only to realise the only web one came from Drupal.

[stof]

This issue is not about API documentation. It is about human-written documentation.
In my experience, API documentation is not that useful (expecially when many classes are about the internal implementation)