How to Write a Killer Add-on Description

Many of you are building some amazing add-ons for MODX that folks would love to use if only they knew and understood what they can be used for. In order to help folks try and then adopt your awesome add-on or extra you'll need to give them more than a few cryptic clues as to what it does and how it works. One of the most important things to realize is that for Revo, most people will only ever see the description in Package Management and if your description is self-referential or unclear they may be missing out on it's awesome functionality. By no means should you write a novel about your add-on but 1 sentence in almost all cases isn't going to cut it.

Here are a few suggestions for getting people to understand your add-on, what it will do for them and why they might use it.

Offer a Use Case (or 3)
The best description of what an add-on does is describe its use. As an example Wayfinder's result is that it enables you to build menus and structured navigation. getResources result is displaying a series of MODX Resources like you might for a blog or product list. Try to avoid what it does or how it does it. No one cares at this point on how your add-on interacts with the MODX or xPDO API.

What Specific Problem Does it Solve
Many add-ons sound like they do similar things, like getResources and getResourceField but they have different uses. If a designer friend or a client asked you what you're add-on did for them, what would you say? If you had a caching add-on when specifically would someone want to use it? A gallery?

Avoid API or Developer Terminology
As mentioned before people are selecting an add-on to solve a problem. How it works and what goes on under the hood are irrelevant to most. If a developer wants to see how it works they can read the code. Regular folks quickly trying to determine if this add-on will solve their problem don't need to be confused by things like $modx->getCollection in the description nor do they want to think about arrays.

If you have examples of great add-on descriptions we can post here, please share them so people will be able to write their own "Killer Add-on Description".

I think there definitely needs to be a link to the addons' documentation and a link to a discussion or support topic/blog as well for more information.

Agreed Mark. It's actually something we're going to implement soon however there are a significant number of add-ons that from reading the name you can't decipher what it does and why you would use it. That would be a great start and then we could work on docs. Discussions is a no-brainer.

What is the approval process like on MODx HQ's end for getting something added to the main repository? This may sound anti-open source, but would requiring a link to documentation (preferably on rtfm, but at least somewhere) before approval be possible as a business rule?

< rant >I know we want quantity, but quality of add-ons is important, too, and the best add-on in the world is practically useless without documentation (unless you're willing to dig through the source, which a lot of people aren't). There are several I could name (but won't) in the repository right now that might've met a need I had, but I would've never known it based on the limited documentation or description.< /rant >

Aaron, your "rant" is really the point of this thread.

I will say that for most developers the workflow is this: build out a cool add-on for a paid project their client asked for, abstract it a bit for general use, share it with the community and then move onto the next project.

I think there may be ways for devs of add-ons to get better/any docs including putting their project on github and inviting collaborators.

Name is not so important as:

1) well-written description like Jay said
2) documentation that can be understood by non-programmers
3) examples and tutoirials for non-programmers -- examples and tuts illustrate, explain, demonstrate the use cases

MODx should if possible please promulgate certain standards:

1) improve the ability to create packages as other people have noted this is much harder than it needs to be

2) define what files can and should go where for a consistent install experience. One addon I tried, not named here, seemed to throw files all over the place, and threw in its own CSS, I gave up on it fast...

3) do NOT put your own CSS -- always defer to the end user's site CSS -- if you want to suggest CSS great BUT have a &noCSS toggle to turn off the addon's CSS and use the site's CSS, better yet, write your code well enough that it does not require any custom CSS to work properly unless someone wants to custom-CSS it

4) I know it could make forum management difficult but as many as possible addons should have their own forum sections

5) no documentation buried in source -- all docs placed where they are easy to find -- rtfm.modx.com.

Thank you for reading this, Tom

There are several I could name (but won't) in the repository right now that might've met a need I had, but I would've never known it based on the limited documentation or description.

Please do note them (feel free to send via email if you want) - perhaps there's something we can do quickly fix that up.

I will say that for most developers the workflow is this: build out a cool add-on for a paid project their client asked for, abstract it a bit for general use, share it with the community and then move onto the next project.

I can definitely vouch for that strategy (though I prefer building it with open source in mind earlier on in the process). It works fine if it's not too high maintenance (eg SubscribeMe) and you're willing to support it.

Tom, I think the things you mention are more about the package and development itself (I think this topic was intended for the descriptions you see in the package manager or extras site). I think the "Building an Extra for MODX Revolution" is pretty clear in where things should be placed, but perhaps we can make an additional document with a checklist of generic development standards to meet. Sounds like a separate topic to me though

4) I know it could make forum management difficult but as many as possible addons should have their own forum sections

I've got a number of addons that have a single forum topic, and that works great. If addons really get huge followings a forum section is desirable, but I think it would be unneccessary clutter for 9/10 addons currently available. We do need a dedicated discussion place though, I agree with you on that.