search

lando / docs

The main docs site for Lando
https://docs.lando.dev/
GNU General Public License v3.0
20 stars 56 forks source link

Better lando.yml Documentation #270

Closed spencerthayer closed 6 months ago

spencerthayer commented 6 months ago

I spend more time googling solutions for Lando configurations than I would like. I even use ChatGPT. It would be ideal if there was a singular resource for Lando configurations that were written to work out of the box. The best example I can point to is that your bare-bones PHP configuration does not work with copy-and-paste.

services:
  myservice:
    type: php:8.0
    via: nginx
    webroot: www

Getting PHP to work requires a lot of tweaking the file, all of which isn't even remotely hinted at in the documentation. One must have a good understanding of Lando to know the system's quirks. I spend so much more time explaining how to get Lando running on Jr. Dev local machines than I care to. And if you had usable documentation, I wouldn't have to.

In fact, I use the Lando documentation as a test to see if a new hire or contractor will be a problem solver. If a junior Developer can figure out how to get a Lando environment running based on the terrible state of the existing documentation, then that means they know a) how to read a lot of documentation and b) how to parse that information to read between the lines and figure out solutions for themselves.

So, in that respect, the terrible documentation is nice. But it's probably not a great thing for onboarding new users though.

I would recommend hiring someone to rewrite your documentation.

AaronFeledy commented 6 months ago

You're hired!

AaronFeledy commented 6 months ago

In all seriousness, if you're finding issues in the docs and working out solutions, please submit PRs with your fixes.

reynoldsalec commented 6 months ago

+1 to @AaronFeledy's comment. Specific feedback in the form of a PR is golden...in the case of the PHP example, I think you're basically saying that you'd prefer the example to be:

name: "my-app"

services:
  myservice:
    type: php:8.0
    via: nginx
    webroot: www

...instead of just detailing the services section.

When I get new devs started with Lando, typically it's on established projects where they just need to lando start, but I think the four pages in Getting Started do a good job on giving folks a holistic understanding: https://docs.lando.dev/getting-started. Do you have any specific suggestions on those @spencerthayer?

In general we've historically had very positive comments regarding the docs, but would be good to know where your devs are getting lost.

pirog commented 6 months ago

@AaronFeledy @reynoldsalec have fun but count me out on this one ;)

reynoldsalec commented 6 months ago

Aww, Pirog has not CONSTITUTION for documentation :)

Definitely follow-up here @spencerthayer if you have some more specifics (especially re:my last comment) or feel free to DM me on the Lando Slack (https://www.launchpass.com/devwithlando) if you want to jam on this more, open to thoughts but just want a little more specific GRIST for the mill.