Tweaks for PHP client Markdown files suggested by markdownlint#7779
Tweaks for PHP client Markdown files suggested by markdownlint#7779wing328 merged 1 commit intoOpenAPITools:masterfrom dkarlovi:feature/php-docs-reorg
Conversation
|
Failures unrelated, the build process seems flake-prone. |
| {{{appDescriptionWithNewLines}}} | ||
| {{/appDescriptionWithNewLines}} | ||
|
|
||
| This PHP package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@wing328 as discussed in #7530, the "growth hacking" effort is possible without it being overwhelming.
From the POV of the:
- generator developer, the generator is the most important thing, the code generated is a side-effect, just test files.
- generator user, the point of the generator is to generate the best possible package, not promote the generator itself, perpetuum mobile style. :)
- 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
@wing328 what about these changes? |
Summary
This is a set of tweaks to the generated documentation of the
phpgenerator, based onmarkdownlintand 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
./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.master@jebentier (2017/07), @dkarlovi (2017/07), @mandrean (2017/08), @jfastnacht (2017/09), @ackintosh (2017/09) heart, @ybelenko (2018/07), @renepardon (2018/12)