[PROFILES] Add usage details

[jeremyharris]

It would be cool to give people insight into how to get started using a plugin. For example, screenshots if appropriate, or a "quick start guide." Ideally, it would something easy to grok for new users. A simple getting started guide (1-3 steps) would be awesome, instead of trying to understand all of the "expert" configuration options readme's usually include.

Debug kit

Official CakePHP Debug Kit Git Repository

Why use this plugin

• It makes debugging easier
• Allows you to debug ajax
• Gives you insight into where your app might be slow

How to get started

1. Add 'DebugKit.Toolbar' to your components.
2. Load it up: CakePlugin::load('DebugKit')

What it looks like in action

[ some sort of screenshot ]

[jameswatts]

There have been quite a few complaints in the community regarding the state of documentation for CakePHP plugins out there. While we're not responsible for these plugins, neither can we force people to write great docs, we could give them a template or a guide to at least provide a good base to work from.

A few suggestions I can think of for the sections:

• Brief description
• Main features
• Requirements/dependencies
• Setup/configuration
• Documentation (this is a very generic concept, not sure if there should be more concrete sections)
• Examples (in my experience examples are sometimes worth a thousand words)
• Screenshots (would only be relevant for plugins with a UI, as I think the examples would cover the rest)
• Support (which support channels the plugin author prefers people use)
• Contributing (some people have specific strategies regarding contributions, which branch to aim PRs at, etc)
• License (assume MIT if none specified?)

I think it would be ideal to not remove the focus from GitHub, so maybe we could ask them to add a file at the base of their repo that we search for, say, CAKEPACKAGE.md for example. This would contain this structure, or whatever structure is defined (the CakePHP docs markup comes to mind).

[jeremyharris]

I like the idea of creating a basic guideline that makes it easy for users. I also agree that we should not remove focus from Github or fall into the trap of recreating some of their functionality. I'd rather not see this project go the way of the bakery. A lot of that metadata exists in composer.json. We could create a simple tool that generates it for you based on form fields, making it super easy for users to get started.

That all said, it's getting a bit ridiculous how many meta files we're creating nowadays for a single repo ;)

Want to share code with the world? Cool, it's easy!
Cool. It's easy! First, commit your code. Add a README.md so people know what's up. You wrote tests, right? Cool, you need a .travis.yml so we know they pass at any given time. Make sure to add a composer.json so people can get it there too. Also, if you want people helping out, add a CONTRIBUTING.md file. Want it in Cake packages? Cool, just add CAKEPACKAGE.md/json.

[jameswatts]

Having a generator for the file would be nice.

[josegonzalez]

I'll come up with a doc for this. I had https://gist.github.com/josegonzalez/903066 a while back, but I think the following should be done:

• Change to markdown, since it rulez.
• Modify it to add sections/rework sections jameswatts has indicated.
• Write a tutorial on how to effectively document your cakephp code. A video would be good, though I don't know that I'll have time for it.
• Link to tutorial on the cakepackages homepage
• Add a news article on bakery for this to publicize the info. Tweeting and facebook etc. would also be good
• Add the template to bake when you bake a plugin, or even as an option. Could be cool for apps as well.

I think not adding another file to the repo is key. If we can just standardize readmes, I think most people would be okay with that.

I can also try and write something that checks all repos for readmes, flags them, and then we can work through them making pull requests with simplified readmes. This would also maybe give us the chance to vet repos and potentially prune out things in cakepackages that shouldn't be there anymore. Just a thought, don't know that I'll do this.

For the last line-item, that may be something we should talk about with the rest of the cake core. Maybe not something we do for 2.x - will there be a 2.4? - but definitely something we could do for 3.x. Thoughts?

[davidyell]

👍
This sounds like a great idea. I've been trying to keep mine inline with the normal ones, but having a template would be very handy.