Documentation

[sagikazarmark]

Currently we have a separate documentation repository. The main reason I separated it is that this way we can have one documentation for all the adapter-utility-messageFactory-helper thing. Should we keep that or separate documentation into their own repositories? (By that I mean documentation should go into the repository it actually documents)

Adapters probably doesn't need a separate documentation page (README is enough?) as configuring a client is relatively easy. Inject the Guzzle Client for example, done.

Projects that need documentation:

• Adapter/Client
• Message Factory
• Plugins
• Discovery

So, should we keep all these in one repository or put them into their own repo?

Downside would be VCS: documentation fixes also require tagging releases. This might be confusing for example in the contract: nothing changed (except the docs), but a new release is out.

[hannesvdvreken]

I'd use version branches for older documentation, no?

adapter/client, message factory, plugins, discovery: their major version numbers will probably go up pretty much in sync.

Documentation for adapters: code samples in readme files should suffice.

[sagikazarmark]

I am sorry @hannesvdvreken but I am not sure how your comment answers my question. 😜

Sure, we can have version branches for every major version, but how is it related to the location of documentation?

[hannesvdvreken]

Haha you're right, I didn't answer the posed question:

I believe a single documentation repo should be ok to bundle all documentation.

[sagikazarmark]

If we go that way, we should rename the repository to packageName-documentation.

[hannesvdvreken]

If the organisation decides to have more than 1 purpose: yes. For now it doesn't. Just http adapters. Repo name is fine imo.

[sagikazarmark]

Well, even the organization name was chosen because this way we can have multiple purposes. Everything that is PHP and HTTP has place in the organization.

[dbu]

i would try to keep this one documentation. everything we do in here should be related. doing completely unrelated things would be kinda strange. i think the separate repository makes sense as there are different parts of the same thing. it will make it a lot easier to cross-link in the doc than if we would have doc in each of those repos. we can branch when a major change happens, otherwise just having information since which version a feature is available should be enough. (much like the symfony doc does). and yes for the adapters we can just have a list in the doc that links to the repositories and explain setup in the readme.

[sagikazarmark]

doing completely unrelated things would be kinda strange.

Do you refer to my "Everything that is PHP and HTTP has place in the organization." sentence?

I agree, we should keep one docs.

[dbu]

yes i did.
ok, so lets keep the documentation repository :-)