Tweaks for PHP client Markdown files suggested by markdownlint

[dkarlovi]

Summary

This is a set of tweaks to the generated documentation of the php generator, based on markdownlint and other similar tools packaged in my https://github.com/dkarlovi/docker-docqa Docker image.

The main README was slightly rearranged to make it more readable, moving the parts a package user would actually be interested in to the top.

See an example here https://github.com/flexolabs/reddit-client

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• If contributing template-only or documentation-only changes which will change sample output, build the project beforehand.
• Run the shell script ./bin/generate-samples.shto update all Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
• File the PR against the correct branch: master
• Copy the technical committee to review the pull request if your PR is targeting a particular programming language.

@jebentier (2017/07), @dkarlovi (2017/07), @mandrean (2017/08), @jfastnacht (2017/09), @ackintosh (2017/09) heart, @ybelenko (2018/07), @renepardon (2018/12)

[dkarlovi]

Failures unrelated, the build process seems flake-prone.

[wing328]

Personally, I prefer putting this block on top for growth hacking but I'm ok to give your suggestion a try to move it to the bottom of the page.

[dkarlovi]

@wing328 as discussed in #7530, the "growth hacking" effort is possible without it being overwhelming.

From the POV of the:

1. generator developer, the generator is the most important thing, the code generated is a side-effect, just test files.
2. generator user, the point of the generator is to generate the best possible package, not promote the generator itself, perpetuum mobile style. :)
3. package user (the developer using the generated code), the generator is totally irrelevant, it might as well not exist, what's important is the code offered in the package, how to use it and get stuff done.

POV in 1. and 3. are in total opposition, this change is trying to shift the focus a bit more from being laser focused on 1. a bit toward 3. to better realize 2. The goals of 1. should still be realized, but in a more subtle way.

[dkarlovi]

BTW this same issue is visible here: this URL is not the homepage of the package built, it's either the info.contact.url provided in the spec or something the user provides, exactly the same issue as the authorship/license.

[wing328]

the generator is totally irrelevant, it might as well not exist, what's important is the code offered in the package, how to use it and get stuff done.

Many users still not aware that the API clients can be auto-generated instead of manually written. It doesn't hurt to make them aware there's such thing called OpenAPI Generator that they can use to generate code.

[dkarlovi]

@wing328 I understand that as do I understand your desire to promote the generator, it's perfectly understandable and not unreasonable.

My intention here is to point out generator's users have no inherent interest to promote the generator, they're not its core developer team. What they want from the generator is generating high-quality code which they can offer as "SDKs" for their API's users (or use themselves). The generator for group 2. is a tool, a means to an end, it's not the destination.

The group 3. doesn't care about the generator at all, they're primarily interested to use the code generated, they're twice removed from it, for them, the code generated is the product. The code and the docs generated should reflect that better, aligning them a bit more toward the interest of users of the code generated goes a long way.

It's not about "informing the users of the package about the generator which made the package", it's about the package itself. The meta-documentation obviously has its place, but it's shouldn't be the primary focus.

[dkarlovi]

Think about it like this: if this was a printing press, it would be trying to add a chapter about itself to each book it's printing because it's trying to inform the readers about itself. :) Yes, it's in the printing press's best interest to put the word out, but there's more than one way to do it, being too direct can seem obnoxious and have the opposite effect from the desired one.

[wing328]

I never said the promotional message should be the focus. I'm not against generating a better package. Putting the message at the top of the package doesn't mean we (openapi-generator contributors) are not focusing on the quality of the package.

[dkarlovi]

@wing328 what about these changes?