[RFC] Add Author Notes to Extension MetaData

Note: We are moving the topics of this forum and it will be deleted at some point

Publish your own request for comments/change or patches for the next version of phpBB. Discuss the contributions and proposals of others. Upcoming releases are 3.2/Rhea and 3.3.
User avatar
VSE
Extension Customisations
Extension Customisations
Posts: 670
Joined: Mon Mar 08, 2010 9:18 am

Re: [RFC] Add Author Notes to Extension MetaData

Post by VSE » Tue Jun 03, 2014 5:01 pm

I was thinking of possibly a simpler alternative to what has been discussed here already.

Perhaps we should just encourage extensions to include an optional "docs" folder ???

That way, the ext author could elect to include a README.txt with instructions on how to get the extension set up/configured in the board, or how to use it in the board itself, etc. Really, any sort of Author Notes / DIY Notes similar to what MODX allowed could be put in a README.

They could also add other documentation they may want as well, such as:
CHANGELOG.txt (another item available in MODX but missing from extensions)
EVENTS.txt file if they added events to their extension and want to document them for other users
FAQ.txt if they feel it necessary to provide one
etc...

It would also allow some authors to get really creative and create a "branded" README.html for example, with their own styling, graphics and logos and other fun stuff!

Also, in certain common support requests, the author may be able to simply refer them to the DOCs folder ;)
Has an irascible disposition.

User avatar
MichaelC
Development Team
Development Team
Posts: 889
Joined: Thu Jan 28, 2010 6:29 pm

Re: [RFC] Add Author Notes to Extension MetaData

Post by MichaelC » Tue Jun 03, 2014 5:19 pm

The original idea when we did all the extension metadata was to add author-notes to extra but I forgot to implement it, it was merged and it only got mentioned again after the fact.

There are some notes the author may want to highlight and 90% of people installing extensions won't read readmes etc. Simply add it to the extra in the file that is designed for metadata (this is metadata), parse it like everything else is and show it on the details page. Other docs (such as a changelog and readme) the author can add in a docs/ folder if they want, but that is a different issue I think and author-notes can always refer to the readme.

You shouldn't say 'When they come to support you can refer them to ...' but instead how can we make it easier/simpler so they don't need to come for support in the first place. That saves those doing support time, makes everyone's life easier and they are less likely to give up and just not use the extension.
Formerly known as Unknown Bliss
psoTFX wrote: I went with Olympus because as I said to the teams ... "It's been one hell of a hill to climb"
No unsolicited PMs please except for quotes.

Post Reply