📚 Let's raise the bar: complete documentation for every theme & plugin

[Kanonimpresor]

Hi e107 community! 👋

As our ecosystem of themes and plugins keeps growing, I'd like to start a conversation about something that often gets pushed to "later" — proper documentation.

We all know the feeling: you find a great plugin on the repository, install it, and then spend hours digging through PHP files trying to figure out what it does, how to configure it, or what changed in the last update. We can do better, and good documentation is what separates a hobby project from a tool people actually adopt and contribute to.

What I'm proposing
When you publish (or update) a theme or plugin for e107, please consider including:

📖 1. README.md
A clear front-page for your project answering:

What does it do? (one-paragraph elevator pitch)
Why would someone use it?
Requirements (e107 version, PHP version, dependencies)
Installation steps
Quick start — get the user to first success in under 5 minutes
License & credits

📘 2. User Guide
A document written for the end user, not the developer. Cover:

Admin panel walkthrough (with screenshots!)
Frontend behavior
Configuration options explained in plain language
Common use cases & examples
FAQ / Troubleshooting
Multi-language if your audience is international

📝 3. CHANGELOG.md
Following Keep a Changelog format:

Versioned entries with dates
Grouped by Added, Changed, Fixed, Removed, Security
Migration notes when there are breaking changes
This is gold for users who need to know what's safe to upgrade

🗺️ 4. Roadmap / Next Steps
Even a short bullet list helps:

What's planned for the next release?
Known limitations
How can the community contribute?
Open issues you'd love help with

🏗️ 5. Architecture notes (optional but valuable)
Database schema
File structure overview
Hook points & extension API
Coding conventions you follow
A practical example

While building the Booking plugin I tried to follow this approach as a reference model. The repo includes:

✅ README.md with installation, features, and screenshots
✅ MANUAL_USUARIO.md — full end-user guide (multi-language: EN/ES/PT)
✅ CHANGELOG.md — every version documented
✅ ROADMAP.md — what's planned and why
✅ GUIA_DESARROLLO_PLUGINS_E107.md — a 2000+ line e107 plugin development guide born from this project, contributed back to the community
✅ Inline PHPDoc on every class & method
✅ Translated language files (English, Spanish, Portuguese)
It's not perfect — and that's the point. Documentation grows with the project. Start small, but start.

Why this matters
🚀 Adoption: people install what they understand
🤝 Contributions: documented projects get more PRs
🐛 Less support burden: a good FAQ saves you 80% of repetitive questions
🌍 Inclusivity: non-English speakers and newcomers can join in
⏳ Future-you: in 6 months you will be the one re-reading your own docs
Let's discuss
What documentation patterns work for you?
Should we propose a documentation template as part of the e107 _blank plugin scaffold?
Would a community-maintained "documentation checklist" in the wiki help?
Any tools you recommend (MkDocs, Docusaurus, plain Markdown, etc.)?
Looking forward to your thoughts. Let's make the e107 ecosystem not just powerful, but welcoming. 💙

— Martin / LandingPro

[Jimmi08]

You are too forward. Your documentation is awesome but people nowadays doesn't read this type of docs. They ask google (AI) and wait for answers. So gitbook or any blog, wiki on github is for me better than write code just for documentation, I personally don't have time for this. From today I will try to do more descriptive issues, any AI can create documentation for issues and code itself. I am against everything that is adding "bytes" to source code. Put it online and I agree, not in code itself. But there is middle gold way for this.

And people install what they have recommended by somebody - and nowadays e107 has very bad reputation. Just ask AI about it.

First thing is to have what to install. And e107.org is not way how to do it.

By the way, I personally almost never read documentation :)

[Kanonimpresor]

Hey @Jimmi08, fair point — and honestly, none of us have time for documentation. 😄

But the reality is that AI already handles most of the writing. Describe what the plugin does, paste the main PHP classes, and ask for a README, a changelog, and a user guide. Maybe 20 minutes total. The hard part is knowing what to document — the AI handles the rest.

Your idea about descriptive issues is a great middle ground. Issues + inline PHPDoc + a minimal README is already 80% of the value. Different workflows for different people — and that's fine.

But here's the concrete case for documentation: when someone asks an AI "what CMS should I use?", e107 doesn't even show up. That's not just a reputation problem — it's a content problem. AI tools recommend what's discoverable and well-described. No README, no visibility.

And beyond the community angle — there's a practical one. If you sell or distribute a plugin, good documentation means fewer support tickets. Users with a clear guide in hand don't need to open an issue every time they get stuck. That scales, whether you're a solo developer or a small team.

As a next step, would it make sense to propose a minimal documentation checklist as part of the e107 plugin scaffold? Not a requirement — just a starting point that anyone can adapt to their own workflow.🙂

— Martin / LandingPro 🚀🚀🚀

[Kanonimpresor]

Regarding "I am against everything that is adding bytes to source code" — let's put that in perspective:
WordPress 6.9.4 → 34.4 MB
OpenCart 3.0.3.9 → 16 MB
e107 2.3.4 → 14 MB
e107 2.3.4 Lite → 12.2 MB
e107 is already the lightest of the three — and still has a Lite version on top of that. WordPress nearly triples e107's footprint. The bytes were never the problem.
The real problem is that nobody knows e107 exists. We keep debating things that cost kilobytes while the actual issue — visibility, discoverability, showing up when someone asks an AI "what CMS should I use?" — goes unaddressed.
A README doesn't bloat a CMS. Silence does.

[Deltik]

@Kanonimpresor: I don't have complete thoughts on this discussion, but as I wrote in my announcement post in #5672, I do have a vague direction:

My preference is documentation as code: self-documenting code, contracts that link what's documented to the coded behavior, and citations enforced like Wikipedia so claims stay traceable. That's my ideal, though.

In practice, I've been so busy getting a grip on the current state of e107 affairs that I haven't had the bandwidth to think about the broader documentation needs. This is an area where I'd welcome community leadership. If someone wants to own a documentation strategy and propose it, I'll review it seriously.

[kreossino]

I strongly believe that e107's official guidelines and comprehensive technical reference documentation should be publicly accessible and updated, just like they used to be in the past.

Nowadays, detailed public documentation is critical not only for human developers but also for AI models. Without a rich, publicly available knowledge base, AI tools cannot properly learn about e107's architecture, which prevents them from helping developers stay informed about updates or supporting the CMS's much-needed rebirth.

While WordPress dominates the web today, it has arguably become a bloated ecosystem of mixed code and paid plugins for almost every single feature, often leading to poor SEO performance in my opinion. However, thanks to its massive community, it benefits from new themes and updates on a daily basis.

This is exactly why e107 stands out. I love e107 for its incredible flexibility, its lightweight core, and especially the 'Plugin Builder' that allows us to manage every part of the code in a clean and agile way. Bringing back strong, public documentation is the key to helping our community grow and showing the world what this CMS is truly capable of.