we should enhance the overall workflow before talking about details

As someone else would say in here: ;-)

Thanks for your question - At this time we are only using github as the place to submit code fixes, the actual reporting of issues and testing fixes is still taking place on Joomlacode.

In this case I would suggest that you ask this question either at the Joomla forum (http://forum.joomla.org) or the CMS mailing list on Google Groups (https://groups.google.com/forum/#!forum/joomla-dev-cms)

Imho, the way and the place this long question is asked (making in advance a thumbs down almost look ridicoulus) has the potential to bias the answers. ;-)

So while warmly welcoming documentation in general, for that question on the CMS repository, I clearly give a Because of:

1. its bias ;
2. the fact that by adding rules, it would raise the barrier of submitting contributions for volunteer contributors (while uncertain of the PR outcome), instead of lowering it ;
3. It's a details question while gets asked before the related large FR submissions workflows are improved ;
4. I do not know that much good doc writers that are also good software developers and the other way around too ;
5. that it doesn't take in account how volunteers and teams work and how documentation gets gradually improved ;
6. As doc is separate from code at this time, it will mix documentation of submitted PR with existing doc.

As a PLT member, I'm almost inclined to make this an official vote. I'll discuss it with the other 9 members.

Amended contributing guidelines should also include that PR's without proper documentation be closed immediately, until such documentation is rendered. PR's without documentation should not be entertained.

@Beat, I can send a PR for the CONTRIBUTING.md file if that makes you happy but this is about changing a file in this repository (maybe you aren't familiar with how Github works with this special file). It doesn't matter to me how we decide. As for the discussion, it's already happening. The link is in the issue description in case you missed it. It would be better if you could discuss the devil in the detail there - it just keeps voting threads cleaner (don't worry, it took the PHP-FIG group a while to get people used to it as well).

The PLT is discussing this, and will have a decision in the coming weeks. Thank you Andrew for raising it and Beat for pointing out your concerns.

For the community members reading this, please let your position be known, either for or against, so the PLT may make a more informed decision.

...and please use the above mentioned thread for discussions.

Thank you.

This is what I'm already doing so here. I've asking this for some time.

We have to find the way to deal with the current docs though. Projects that do this include the documentation in the project itself which probably is not an option in joomla.

We can maybe add a status for task when the issue is closed to "migrating documentation" which means that we expect that someone gets the info in then PR ans puta it on place. I don't like this but with the current documentation it will be hard anyway.

If we just used github...

I've been doing loads of work on docs and despite that I'm voting because I think it will discourage contributions

, I'm too often reverse-engineering the code to learn the API.
But there should be option for review/ corrections for submissions by non-native English contributors (like me )

Although I agree it will discourage contributors, I feel it will increase the overall quality of the contributions.

would love to see how many of us that voted here actually ever contributed code to joomla.

while we are at raising the contribution barrier even higher, why not require a masters degree in computer science and English literature and post graduate studies in managing conflict in order to be allowed to submit code.

Honestly we need to take a moment and think about our environment, our non English contributors, our volunteers.

This is NOT the way to improve, it's just a big step back.

imo

@nickanti, I think that if you add example usage code in the wiki instead of formal documentation will be right balance. For example, I recently encountered with 3.2 new release - one of the developers in our community ask how to implement this new feature: #1644 and didn't get and document about this feature.

@nickanti I resent your statement about contributing code... I contribute in other ways, and I'm definitely affected by new features that have no documentation. So therefore I am just as much entitled to a vote as you are. If you would like to take this discussion off list, I'm happy to do so. You have my skype ID.

@nickanti I would suggest you go over to the contributors page for the CMS (https://github.com/joomla/joomla-cms/graphs/contributors) and for the Framework (https://github.com/joomla/joomla-framework/graphs/contributors) and check to see how many of the 's have contributed code to the project instead of slinging mud. You'll be pleasantly surpised that I personaly know that 11 / 13 of the 's have submitted copious amounts of code.

Incidentally, out of the 4 's, I know of only 1 that has contributed actual code. (1 I know has contributed a lot of documentation, thanks @wilsonge)

Thanks for taking the time to research. :)

Do bug fixes count?

Does testing count?

Does financial contribution count?

@nickanti Your question was "I wonder how many have contributed code" so that's what I was answering. Of course those other things count, but as I said, I was just answering the question that you presented. Don't be offended when facts are presented.

My question was:

would love to see how many of us that voted here actually ever contributed code to joomla.

notice the -->> us ?

On 12 Νοε 2013, at 9:47 μ.μ., Don Gilbert notifications@github.com wrote:

@nickanti Your question was "I wonder how many have contributed code" so that's what I was answering. Of course those other things count, but as I said, I was just answering the question that you presented. Don't be offended when facts are presented.

—
Reply to this email directly or view it on GitHub.

oops - sorry - did not realize that replies to emails are recorded - stopping.

@nickanti

I +1'd

I've contributed to the CMS, and have a PR pending right now.

I also have a masters in computer science, and qualifications in English
language and literature. Plus 10 years experience of managing engineers
(software and hardware), so have had plenty of time to practice conflict
resolution.

That being said, it doesn't make my +1 any more or less important than
anyone else's.

So when you live in a glass house, you should try not to throw stones.

Chris.

Chris Jones-Gill
KISS Web Design
Company number: 7486736
VAT Registration: 107800539

Sorry to continue this - really - just proves how difficult it is to even contribute to a conversation.

My point is that we should find ways to lower the barrier instead of raising it.

(BTW - I also have a couple of MS degrees and I also write technical documentation - but I still feel that insisting on up-front documentation in order to get new features in Joomla is a step back)

We aren't asking for thorough notes with every detail broken down. A high
level overview (what is it, what's it doing, how to use it) is all you
would need. For features I implement in my projects, I have the first two
answered in my mind before laying down a line of code and I'll document the
how once everything is sorted. So for me, it is a matter of taking those
planning notes, making them public consumable, and posting them.

On Tuesday, November 12, 2013, Nick A. wrote:

Sorry to continue this - really - just proves how difficult it is to even
contribute to a conversation.

My point is that we should find ways to lower the barrier instead of
raising it.

(BTW - I also have a couple of MS degrees and I also write technical
documentation - but I still feel that insisting on up-front documentation
in order to get new features in Joomla is a step back)

—
Reply to this email directly or view it on GitHub#2496 (comment)
.

Keep it on track guys. If you want to require tertiary qualifications to
contribute code, please start your own voting thread and discussion. This
prososal is agnostic on the matter.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - free tutorials and videos on Joomla
development

As said in the discussion thread....
from http://developer.joomla.org/cms/development-strategy.html

Provide basic documentation for all new additions to the code base.

So, I'm not sure what we are voting about anyway

Well, I think the aye's have it so I'll organise a pull request. Thanks all.

I'm all for lowering the barrier for contributing, just not lowering the
amount of thought and consideration for others - by which I mean throwing
some code at GitHub and expecting someone else to read it, understand it,
test it and document it.

A simple 1 page doc (any format) to cover the basics should be a simple job
that takes as little time as sending an email. After all, if you have coded
something you probably have it all in your head already.

If the code for a new feature has to be read and understood, deconstructed,
and documented by someone other than the coder (or team of) - months after
it has been merged - the job becomes much harder and longer. A single page,
even rough and badly spelled with poor grammar (that's not a dig at
non-english speakers), is a great help for everyone. I know lots of
contributors are not native English speakers (or writers), and I would hate
for them to feel excluded - the documentation does not need to pass any
English exams, just to give everyone an idea of what, why and how.

No engineer I've ever met likes writing documentation, it is just something
that needs to be done so that the next person isn't left in the dark. We've
all been in the situation where we have to change some undocumented thing,
and that's worse than spending a little time stopping someone else being
left in that same situation.

Once everyone knows what the requirements are, it will be easy to make that
part of the development process. There will be good examples from the
framework and platform to reference.

If I have to hunt for more than a couple of minutes for some documentation
about something that needs testing, I am far less likely to test it. I just
like to see a bit of information without having to dig through the code.
It's just the way I am.

Documentation is a necessary part of development. Just as necessary as
testing and code formatting.

Chris.

Chris Jones-Gill
KISS Web Design
Company number: 7486736
VAT Registration: 107800539

On 13 November 2013 07:34, Chris Jones-Gill notifications@github.comwrote:

No engineer I've ever met likes writing documentation.

I must be genetically malformed because I am an engineer and I actually do
like writing documentation :)

But you are right. By the time you write a few paragraphs to explain what
you've done, you've probably already met the minimum "documentation"
requirement. Anything more is a bonus and it's about distributing the work
load more fairly and evenly.

Regards,
Andrew Eddie

Ah, ok, if it's just a "few paragraphs of basic documentation" as minimum requirement, it's a different story, as long as we don't get pedantic on it. Thanks for the precision!

Sure, in that case, from me, it's a , no issues there. Actually I think all my past FR PRs had that already either in the PR or in the code anyway already, or in both. Actually, most FRs have testing instructions and basic documenting descriptions anyway to pass tests and approvals, so not sure why we make a big story here.

Regards,
Beat

Ah, ok, if it's just a "few paragraphs of basic documentation" as minimum requirement, it's a different story, as long as we don't get pedantic on it. Thanks for the precision!

I'd add to that "don't be lazy". From you, I would expect you to set a good example and organise good documentation with your contributions, not just the bare minimum to get a "pass", so that others can follow your exemplary lead ;) You never know, it might even lead to a few Community Builder sales if people see how good your contributions are :P

@oc666 Off topic a second - about that pull request - the reason I haven't taken time out to document that is because it's already managed to be broken - and I'm trying to figure out what in the JavaScript has broken it (JS isn't my area of speciality) :| I'm trying to keep it hidden until it actually works again

The other thing that I'd say is my hope is that if any aspect of the
contribution needs "more work", be that better documentation, more unit
test coverage, etc, we add it to a backlog so that people can find out what
needs to be done. In the Framework we just use the Issue tracker itself and
some special labels.

If everyone develops good habits, and let's be honest a potential employer
or client could be reviewing your Joomla contributions to see how good you
are (if you are complaining about doing documentation, how is that going to
look to a client that might want to hire you ... food for thought ...), it
means less things fall through the cracks. It might still take time to get
things done, but at least we have an idea of how much we have to do.

I'd also add that don't stop moaning about the docs either because we still
need to be able to think about what in Joomla needs to be improved - and
everyone knows docs are the elephant in the room!

On 13 November 2013 00:04, Andrew Eddie notifications@github.com wrote:

The other thing that I'd say is my hope is that if any aspect of the
contribution needs "more work", be that better documentation, more unit
test coverage, etc, we add it to a backlog so that people can find out what
needs to be done. In the Framework we just use the Issue tracker itself and
some special labels.

If everyone develops good habits, and let's be honest a potential employer
or client could be reviewing your Joomla contributions to see how good you
are (if you are complaining about doing documentation, how is that going to
look to a client that might want to hire you ... food for thought ...), it
means less things fall through the cracks. It might still take time to get
things done, but at least we have an idea of how much we have to do.

—
Reply to this email directly or view it on GitHub#2496 (comment)
.

@eddieajau I must be genetically malformed because I am an engineer and I actually do like writing documentation :)

lol.

As with any sweeping generalisation there are exceptions that prove the rule.

Genetically modify engineers to like writing documentation... I see a DNA hacking kickstarter in that idea.

Seriously though, some good examples of what is needed as a minimum, as well as examples of what is preferred. Plus an example of an ideal submission would be useful - even if it is only ever used as a target that never gets hit.

Chris.

Labels "Needs more xyz" is a good idea and are much more contributors-friendly than "closing immediately" and "rejecting" PRs. Think on how JED handled minor mistakes in the past. We don't want that kind of stuff anymore as an experience. We need to stay as friendly as possible with our contributors, they are the blood and the future of our project.

Agreed.

I vote for a "Needs more Cowbell" label.

Now that I definitely will vote for

+1 (doing this +1 from http://issues.joomla.org/tracker/joomla-cms/2496 ) ^_^
You may blame the J!Tracker Application for transmitting this comment.

While I'm not a developer, I'd like to point out that if you're asking people to test a feature, you reach a bigger testing audience when you take the time document what you'd like them to test properly. I've seen plenty of items on the Tracker where I had no clue what I was supposed to test. :)

Uh oh, the issue tracker guys have a new toy :)

Its been almost a year since this was last commented on.

This comment was created with the J!Tracker Application at http://issues.joomla.org/.

This recommendation was adopted. See http://developer.joomla.org/news/586-joomla-development-strategy.html#contributor_policy