Can we have some kind of XF suggested guide / template for developers on how to format add on readme's, change logs and configuration instructions?

RobinHood

Well-known member
This was an issue with XF1 that I see being carried over to XF2.

With certain add ons, especially the bigger more complex ones, all of the various options and settings can be all over the place in the admin control panel. New ones will appear in places you don't know where to look, or get appended to existing sections with no kind of highlighting or explanation that that setting relates to an add on that's been installed.

If the add on author doesn't have a good read me, or video tutorial (very useful btw on your recent releases @Jaxel), then it can be so frustrating trying to figure out where all the settings are and how they relate.

I feel bad for posting questions in the threads sometime as I'm sure many of the questions have been added before and perhaps it's just me being an idiot and missing something because perhaps I'm looking in the wrong place. So I sometimes end up wasting a ton of time hunting around the ACP to find things.

With the release of XF2 there is some amazing, long requested developer documentation. It seems devs are reading this, it would be great it you could also give guidance on how to write a useful read me, release notes, change log etc. to establish some kind of useful standard.

With some add ons, in order to get them to work you may have:

  • A completely new entry in the ACP -> Setup -> Options list, full of configurable settings
  • A completely new entry in any other ACP Main Section -> ACP Sub Section
  • An entirely new ACP Main Section
  • Extra fields or options in any ACP Main Section -> ACP Sub Section (including existing Setup -> Options entries)
  • New user permissions that have to be set for one or more of the following user groups:
    • Everyone
    • Guests
    • Registered Members
    • Mods
    • Admins
  • ^ Some add ons come with permissions pre configured to the best suggested, some require you configure them. This is inconsistent.
  • New node permissions or options that get added and need to be edited specifically for each node
  • New Style Properties that can be edited
    • Sometimes these don't just control style in pure html and css sense, but also more complicated configurable options, this should be explained and pointed out as it's not always obvious to look there.
    • New key templates that you may want to edit directly for some reason.
  • New Cron Entries
  • New Cache Rebuilds
  • New Logs that you can check
  • New Statistics that are added
  • etc
I may have missed some there.

I would really like to see some kind of standard or template examples that dev's can strive to emulate with every add on release, so that when you unzip it you can succinctly get all the information you need to install, setup and configure that add on, and see what's new in this version vs the old version. And exactly what options get added to your install, where to find them and an explanation of what they do, what permissions to configure and options to setup after this install/upgrade. etc.

Encourage all the devs that are releasing these add ons to raise the bar with their own documentation by setting a standard. This will make everyones lives easier and reduce the amount of configuration and headache when buying and installing new ones. It will also make admins much more aware of exactly what is going on with their install and what settings belong to what add on and what ACP features are added, even if it's mundane cron entries or cache rebuilds that might not be used very often. It's fine if you only have a few add ons installed, but once you hit double or triple digits, the amount of options or permissions can be ridiculous and hard to discern if they're not labelled or explained.

I actually made a suggestion years back about highlighting add on options that get added to existing ACP sections, kind of like how @Jake Bunce's nodes as tabs did, so it was crystal clear what options were stock and what were provided by add ons. That would also be very useful, but these docs standards would be a good start.
 
Last edited:

RobinHood

Well-known member
For example, this is exactly the kind of thing I'm talking about. Someone is asking about an add on feature/option and the option is actually in the style properties, where admins may not think to look:

https://xenforo.com/community/threads/content-ratings-for-xf2-paid.133428/post-1227899

I actually had the same query, but spent ages looking for it and I think I figured it out in the end from either the FAQ, searching through the thread or some other way, but if it was listed and explained in the read me in some zipped up docs I could have searched within that doc and figured it out a lot faster.
 

Live Free

Active member
@RobinHood I’m not a developer but I agree with you. Developer documentation, standards for developers, and standard implementations forum admins see are all critical for growing the XenForo development community.

I really don’t see why it’s not a priority. It results in happier forum admins and more, standardized quality add-ons, which attracts more customers. Which means more revenue for XenForo.

Unfortunately, I think developers are going to have to get together and propose thier own standards.
 

Mike Creuzer

Well-known member
There sure are a lot of features in some add-ons, and a lot are ever-changing. Proper documentation is a full time job though, its tough to stay on top of everything perfectly.
 

Snog

Well-known member
This all sounds fine and dandy, but I'm not a technical writer. To employ such a person costs money. Now, if people wouldn't complain about the cost going up significantly for an add-on with well written documentation, I would probably hire someone. But, to keep costs down I simply describe each option as best I can and rely on the end user reading the comments on each option. And actually reading the README.txt file when one is included.
 

mcatze

Well-known member
What's about special agreements between developers and (pro)users/employees?
I made some simple add-ons, language packs etc. and has also many problems during translation about the functions. At my start with xenforo i got an add-on for free to make the translation and documentation in german. Maybe this is a way that some developers can go.
 

Snog

Well-known member
At my start with xenforo i got an add-on for free to make the translation and documentation in german. Maybe this is a way that some developers can go.
I did that once and I'll never do it again. Almost immediately after translation the add-ons I had translated began to appear on sites they shouldn't be on.
 

mcatze

Well-known member
@Snog That should not happend. But yes, this is a risk and as a developer you had your "special" customers. I would not give someone i didn't know my work for free. But you also have customers for years you know and these guys are maybe interested in such work.
 

Jake B.

Well-known member
all of the various options and settings can be all over the place in the admin control panel. New ones will appear in places you don't know where to look, or get appended to existing sections with no kind of highlighting or explanation that that setting relates to an add on that's been installed.
FWIW XF2 does give you a link to all options for specific add-ons on the add-on list

Capture.PNG
 

Jake B.

Well-known member
Something that would be nice is if XenForo also detected when an add-on has settings in the style properties and linked to them too. Perhaps a suggestion needs to be made?
Yeah, surprising they don't have that, probably just link to the style property in whatever the default theme is
 
  • Like
Reactions: Xon
Top