Many things are attributed to Albert Einstein which probably never left his mouth, but one that seems to stick is:

If you can't explain it simply, you don't understand it well enough.

When this is applied to explaining new ideas to people, the new feature you want to get into the Joomla core, simplicity is often a good place to start.

But simplicity is a tough thing to achieve. When looking at great design, code, and inventions, there will be a graveyard of discarded ideas, lines and prototypes on which it is built.

There is a huge amount of craft that takes the fledgling idea and transforms it from a crude idea into a well thought out finished feature.
Once you have honed that new must-have idea, next is the problem of testing, writing it up and describing the use cases.

But do we need to write such documentation, should we waste time explaining and describing? Better to just go on to the next great new feature and do what coders do best... Code.

And there is the issue right before us. The coder is not necessarily a writer, a tester or even a native English speaker.
Just because code is written with English words does not mean the creator is fluent in the default language. So the documentation which “will come one day” is never written, that special day for manual writing never arrives and we don't get the testament the idea deserves.

What happens when there’s no good documentation

So the testers don't have the easy-to-follow tests they should have. The feature doesn't get the tests it needs to become part of the core, and the idea languishes in the queue for a long long time.

If finally it makes it then there's a job for the document writers to work out what it does, how it does it and why it should even be in the core of Joomla. Without that inside knowledge, it's really hard and time-consuming to understand someone else’s work, get behind the idea and do it justice.

Time passes and someone needs the functionality, it's sneaked its way into the core, hidden away, used by just a few and so another programmer comes up with a great idea and makes an extension that does exactly what the core functionality already does, only because they were unaware of it.

It has happened. How do I know? Because I have been there and written such, only to find some time after that it was in the core, just hidden away.

It is a modern-day version of the old proverb, “for want of a nail”.
There are many versions but this is the DC Comics version.

For want of a nail the shoe was lost,
for want of a shoe the horse was lost,
for want of a horse the knight was lost,
for want of a knight the battle was lost,
for want of a battle the kingdom was lost.
So a kingdom was lost - all for want of a nail.

Documentation is our proverbial nail: everything hangs on good documentation. The rest of what is needed will flow.

What happens when there is good documentation

With good documentation when the code first appears in GitHub, tests can be written that makes sense, and instructions to follow how to install and use the feature will be easier.

If the test instructions are easier to understand then not only will the functionality be tested sooner but it will also be tested better, and deeper, uncovering things which perhaps were not intended and can be fixed and refined early on.

The magazine team in one of their highly efficient and never sidetracked planning meetings will schedule an interview with the feature coder and the writer of the instructions to get the full insight.
This article will appear before the release of the feature so that all can know how and when to use it.

Then the hard-pressed documents team will rejoice as they have contemporary well written detailed missives to lift and place in the correct area.

OK, but how are we going to fix this?

So what is this secret sauce that will so dramatically change the way we do things at the moment, I hear you cry?

Introducing Document Buddies.

A pool of writers who are willing to meet with any feature coder to discuss and understand their plans. Someone who can translate the code idea into a well-documented and illustrated article that can start its journey in GitHub as the idea description but morph through the writing process taking on the structure and form needed for the various areas in the Joomla ecosystem.

The process of just talking through the functionality with someone can really help develop the ideas involved. Such writers can help provide a systematic way of recording the feature to be included.

Areas that would need discussing and detailing are:

• Why do we need the feature?
• What user cases will it help us with?
• Where will we come across it in both the administrator and the site side, if it has an influence there?
• How do we install and how do we use it?
• Configuration details, how it can be set up and the scope of such configuration?
• Testing, how to do the tests and clear outcomes of the tests so that it can be easily understood and put through its paces?
• Any side effects, changes to current behavior where that might not be expected.
• Any third party resources involved.

Once this is talked through and the document buddy has an understanding of what is involved, several drafts of the feature idea should take place so that the coder and the document writer are fully on the same page.

With this more detailed instruction the conversation on GitHub should be more informed. That GitHub feedback can also help shape some of the document with the insights and ideas others contribute in the honing process.

Then, when it's tested and tagged for inclusion, the writings in GitHub can form the basis of the magazine article and any docs that need to be written.

The magazine article should fully illuminate the feature to the wider community and be useful in JUG talks to get the message out.

So no longer will I be presenting some neat little feature I knocked together one afternoon, only to be told at a Joomla London User Group that it's already there, just hidden in the core.

I want to be part of the fun! How?

And now, dear reader, it's your turn. If thoughts of yes that's what's needed and if only had always worked like that, crossed your mind, have no fear! You can be part of it, you can join the group of documenteers who will use the power of writing to enhance the code others craft.
There is a group called Document Buddies on Glip that's newly formed to do this work.

We want to keep it fun and productive, helpful and collaborative. So come and join, reach out to This email address is being protected from spambots. You need JavaScript enabled to view it. if you need access to the channel and be part of the solution.

French translation of this article: Accompagner la documentation - Améliorer Joomla sans écrire une ligne de code https://www.joomla.fr/actualites/accompagner-la-documentation-ameliorer-joomla-sans-ecrire-une-ligne-de-code