search

pattern-lab / patternlab-php-core

This repository provides the core functionality for Pattern Lab. It is meant to be used from within an Edition with a PatternEngine and StarterKit.
http://patternlab.io/
MIT License
43 stars 62 forks source link

Update README to be more descriptive and helpful #132

Open bradfrost opened 6 years ago

bradfrost commented 6 years ago

Pattern Lab's edition architecture can be confusing. This is more a global thing than anything, but this repo is a good example. Right now the README says:

This repository contains the core functionality for Pattern Lab. Pattern Lab Core is designed to be included as a dependency within Editions. Turn it up.

We need to include a lot more info on all of our repos so people know which puzzle piece does what, where to go to learn more, and how to think about this particular chunk of code.

cc @bmuenzenmeyer and @EvanLovely.

bmuenzenmeyer commented 6 years ago

I spent a decent amount of time making the Node Core README more user friendly.

https://github.com/pattern-lab/patternlab-node

NamelessCoder commented 6 years ago

Pattern Lab's edition architecture can be confusing.

Pattern Lab's architecture as a whole is confusing, no offence.

I'd like to add an anecdote here. I've been creating a separate edition of PL and I can tell you that even as an extremely experienced developer, it is very hard to understand your repositories' purposes and structures when you come to the project from the outside and it would absolutely help if you describe what each of the different components do and how you use/create them: editions, engines, style guide kits, starter kits, demos, ...

And it would definitely also help if you had some sort of description for people writing editions, what the purpose of all these folders and configuration options are and why they are split into separate repositories.

Or better: improve the architecture so you don't require so many different and tiny puzzle pieces. Provide API for registering things like a pattern engine, then stick all the associated configuration there and allow the PL core to operate the engines you plug in via dependencies. If you do this you can probably reduce the required number of components to one: the engine, which optionally also contains assets for the style guide kit and a basic starter kit collection, and doesn't need a custom edition in order to work.

Also refer to https://github.com/pattern-lab/patternlab-php-core/issues/155 which is another hurdle one has to overcome when writing new editions; currently there is duplicated code and code with PatternLab vendor required by all editions.

Thanks in advance for considering.

bradfrost commented 6 years ago

Hi @NamelessCoder. Thanks for your suggestions. I just want to pop in here to say Pattern Lab is an open-source project managed by people who primarily work on the project once they put their kids to bed at night. In its 5-year evolution, it's grown from a hacked-together PHP-specifiic project into one that's flexible and powerful. A lot of energy went into making that happen and getting that out the door. We're aware that there's a lot of work to do still, especially on the communication and documentation side, and we're thankful to the people who are hard at work making it all happen. So we appreciate your comments for specific improvements, and also appreciate positive, encouraging vibes directed towards the people who make this project possible.

NamelessCoder commented 6 years ago

Hey @bradfrost - thanks for answering. Not to clog up the thread with meta, but I certainly didn't mean any disrespect to you guys who maintain the project. I'm both OSS contributor and maintainer myself so I know exactly what you mean. And I'm all too aware that the thing I suggest definitely isn't a small thing that's going to happen overnight, and is likely the last thing one would normally document/improve about an application. Consider it my napkin sketch of what I'd consider an ideal solution.

I've only known about PL for two weeks but if you think I might be able to help here - for example, adapting https://github.com/pattern-lab/patternlab-node to this repo and/or documenting how editions are created - don't be afraid to put me to work. I'd be happy to give you a hand, I just don't know where and how to start ;)

bradfrost commented 6 years ago

All good, @NamelessCoder! Thanks for your offer to help. I'm sort of the project's spirit animal; @bmuenzenmeyer is the one neck deep of the inner workings of PL and would be able to point you in the right direction.