Requiring Documentation for All New Features

[Nick Savov]

Hi all,

What are you thoughts on the CMS requiring documentation for all new feature submissions before those features can be committed to the core? Currently, we do not have any requirements for documentation for submissions and the responsibility is on the Joomla community at large to document the new features that come in.

The floor is open for feedback and questions.

Kind regards,

Nick

[Brad Gies]

My thought: It would be great if it didn't stop any work from being
done..... but I live in the real world... and I don't want to put any
more blocks in the way of new features ;).

Brad.

> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! CMS Development" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to joomla-dev-cm...@googlegroups.com.
> To post to this group, send an email to joomla-...@googlegroups.com.
> Visit this group at http://groups.google.com/group/joomla-dev-cms.
> For more options, visit https://groups.google.com/groups/opt_out.

[Michael Babker]

It would be nice to get docs, but Brad does make a point about it.  It'd be nice if we had folks who are better with using code and writing docs that could work closely with the teams creating new features to help with this though.

On Sat, Nov 9, 2013 at 10:01 AM, Brad Gies <rbg...@gmail.com> wrote:

My thought: It would be great if it didn't stop any work from being done..... but I live in the real world... and I don't want to put any more blocks in the way of new features ;).

Brad.

On 2013-11-09 11:33 PM, Nick Savov wrote:

Hi all,

What are you thoughts on the CMS requiring documentation for all new feature submissions before those features can be committed to the core? Currently, we do not have any requirements for documentation for submissions and the responsibility is on the Joomla community at large to document the new features that come in.

The floor is open for feedback and questions.

Kind regards,
Nick
--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send an email to joomla-dev-cms@googlegroups.com.

Visit this group at http://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send an email to joomla-dev-cms@googlegroups.com.

[Bakual]

It sure would be nice. We just have to make sure people don't waste time writing docs for a feature which doesn't get accepted. And probably not all features need a doc. But content versioning, tags, install from web and such things should have docs, otherwise developers have a hard time figuring out how it works. The one for content versioning is a excellent example how it should be done ;)

It could maybe be done by adding a new state to the tracker "accepted, needs doc" or something like that. This way people that are good with doc writing would know where to look for work and who to ask for explanations.

With the current time based release cycle, it's probably not possible to wait for docs. We wouldn't get many features since all tend to come in during the last weeks :)

[kisswebdesign]

Do you mean comments in the code, an external document for developers or a user guide - or possibly all three?

I personally think it is a good idea to have as much quality documentation as possible. What defines quality documentation is up for debate though.

From http://www.infoworld.com/d/application-development/how-get-developers-document-their-code-183908

Probably the most effective way to get developers to change their habits, however, is to make documentation a team effort. If a few developers have ownership of a certain module of code, have them give a presentation to the entire team explaining how the code works. In the process of preparing the presentation, they will have done most of the legwork required for formal documentation, and any questions that arise during the presentation will help iron out ambiguities.

How to achieve this is an open source, distributed and leaderless organisation (ie we don't have the equivalent of Dries) is much harder than in a traditional company environment. But a team effort at documentation, run along the same lines as the bug squad events, could be worth trying. But this does depend on what type of documentation you are referring to.

Coders are probably not the best people to write user guides, but there is no reason why they could not use a minimum set of DocBlock headers and have some useful code comments where decisions about algorithm type are made (for example) - and a simple 1 page "what, why, how" is not going to be too time consuming to stop people developing features.

== the following example is deliberately not relating to websites or Joomla! ==

I like to use inline code comments for "Why it's done like this" as oppose to what it is doing. The file/class/function should have a comment block before it that as a minimum should have inputs and output, in addition to any DocBlock headers.

e.g.

// Using a 3 partition quicksort for speed, given that the input data is comprised of a few unique keys

External docs for developers should cover what, why and how - i.e. What the function/class/feature actually does, Why it is necessary and How it is accomplished - without describing the code line by line.

e.g.

WHAT

int I2C-decode(array $stream[], string $register, string $message);

The I2C-decode function receives an input stream from an I2C output buffer as an array and converts it safely to a NUL terminated string of the correct length. The string is passed back by the $message variable, and the register code is passed back in the $register variable. 

The return value is 0 for success or >0 for an error, the error codes follow this projects standard error code format (link to error code doc).

WHY

This is necessary because the characters in an I2C stream can contain sequences that could be interpreted as NUL (eg /0 ) and the message appears to be terminated prematurely. /0 in the stream should be interpreted as an ASCII Slash (0x2f hex or &#47; in HTML) followed by the integer 0 (0x00 hex or &#000; in HTML).

HOW

By reading the first 10 bytes of the stream we get the register that sent the message and the length of the message, then reading each byte up to the length given, and writing the ASCII character to a string we can extract the message in a human readable form. The trailing 16 bytes are the MD5 checksum of the message AND the leading 10 bytes, which is checked against an internally created MD5 hash (using the MD5 library function - link to doc).

Note, the message can never exceed 239 bytes due to the register size.

External docs for users should give high level instructions on the use of the function/class/feature.

e.g.

Connect your test unit to one of your computers USB ports using the I2C-USB converter (link to I2C-USB converter doc).

Run the "I2C message test" program (link to download the "I2C message test" program).

Wait for the "Ready to test" message to be displayed.

Push the "initialise" button on the test unit.

A series of messages from each I2C register will be displayed on the screen.

========

Just my thoughts.

Chris.

[Mark Dexter]

I understand the thinking behind the idea, but I worry that the effect would be to delay new features instead of encouraging more documentation. Even in commercial software companies, docs always lags code. In a volunteer project the problem is worse. 

One problem that is almost inescapable is that the code can (and often does) change significantly right up until a release. So doing docs too early in the process can result in a lot of wasted effort. Then we are faced with the option of delaying the release due to missing docs or proceeding and playing catch-up on docs. We have always chosen the latter, which all things considered I think is the right choice. For example, if we delayed a release until the help screens were done, we would have delayed every release by months (or in some cases years).

Another point is that often the developer is not the best person to write the docs. 

I guess my overall opinion is that we should encourage docs as much as possible. I also don't think it's a bad idea to consider docs when deciding on whether to accept a feature or not. But having some kind of rule would be a bad idea imo. 

Mark

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send an email to joomla-...@googlegroups.com.

[Brad Gies]

Bakual, adding an "accepted, needs doc" state would be a pretty good way of doing it. I think I'd change it to "merged, needs doc", just to make it clear that it's already in but needs documentation.  My opinion is that would be pretty close to an ideal situation given that we can't really force anyone to anything, and it would give people a way to search for code that needs documentation.

Brad.

--

[Andrew Eddie]

On Sunday, 10 November 2013 01:33:48 UTC+10, Nick Savov wrote:

What are you thoughts on the CMS requiring documentation for all new feature submissions before those features can be committed to the core? Currently, we do not have any requirements for documentation for submissions and the responsibility is on the Joomla community at large to document the new features that come in.

Developers have been getting used to it on the Framework. We do require documentation with any completely new features or changes to behaviour. The quality varies and if we see that someone has at least made an effort, the changes will be merged. There is still a backlog of documentation but because of this policy was are further ahead at this point in time rather than further behind. For code, DocBlocks are mandatory and phpcs picks up any misses elements quite well. This is practice I think we can duplication for the CMS.

I think the CMS should be unapologetic about requiring help tags for new "fields" that are used by JForm. I don't think that's unreasonable and I suspect it's the current practice anyway. The problem is what to do with end-user documentation. I think the stance of "we expect you to make an effort" is a reasonable one, and it may mean the contributor has to partner with other people to help get a PR across the line. I would accept end-user documentation in any form - word doc, draft page on docs.joomla.org, a markdown gist (that would be my preferred). It just has to be enough for the docs team to be able to pick it up and not start from zero.

So, I think the rules could be:

1. Your code contributions MUST pass the Joomla code-style rules (this will pick up DocBlocks and such).

2. You MUST provide help text for any form fields that you add with your contribution, or modify existing text where you are changing behaviour.

3. You MUST make some effort to provide basic end-user documentation with new features or changes to existing behaviour.

]

[Andrew Eddie]

On Sunday, 10 November 2013 16:07:32 UTC+10, Andrew Eddie wrote:

1. Your code contributions MUST pass the Joomla code-style rules (this will pick up DocBlocks and such).

2. You MUST provide help text for any form fields that you add with your contribution, or modify existing text where you are changing behaviour.

3. You MUST make some effort to provide basic end-user documentation with new features or changes to existing behaviour.

Sorry - dog jumped into my lap.

We definitely don't want people to have to write a book about things, but at the same time it's not fair that documentation is always left to "someone else". If everyone pulls their weight, then the documentation teams spend more time word-smithing and filling holes than writing complete sections of help content from scratch. Sure, some people will be ticked off but my view is people who are not prepared to make even a basic effort can just write their own extension and find out how hard it is to support without any documentation.

I certainly think the new Issue Tracker can assist with labels where contributors can get help for a variety of things. "Help me do the end-user docs" could be one of them. "Help me clean up the code-style" could be another. For example, I haven't had time to help document the new Template Manager, but I did spend an hour helping with code-style. I think that's reasonable to expect from our community.

My 2c or so.

Regards,

Andrew Eddie

[Valentin Despa]

I find contributing to the documentation (where there is no stub for a topic) very hard.

I would propose to have at least a basic page for each new feature (title, properly organised in a category) where at a later other people can contribute with content.

[Gary Mort]

Not under the current system.  The current system places docs in an external site and everything has to be synced.

Now if you mean every new feature must have a corresponding text file in the docs folder, hell yeah!

IE new feature for the CMS

plugin/editors/raptor  <--- adds the Raptor editor as an option for the CMS

MUST be accompanied by

docs/editors/raptor.???  <-- documents some of the options available on the raptor editor plugin

The problem is, that to require it, you will need to decide on a system to use for documentation.  IE how to embed external links to the Joomla Doc pages, how to cross link documentation, etc.  Do you want it as text information, html, markdown, something else?

Personally, I like plain text in source repositories since that means when I clone the repository I have access to all the docs on my local system along with the code.   It also makes using web based VCS browsers such as Github pleasant[when discussing bugs and api's for linux, it is very easy for me to link directly to the docs in a git repository such as https://github.com/torvalds/linux/tree/master/Documentation/devicetree/bindings/arm

That particular section of documentation was entirely non-existent 12 months ago!  It is only in the past 12 months that it became practically required for all ARM devices to use the device tree for configuring their systems to get their code into version 3.8 and above.   You can see from the sheer quantity of information that it is quickly added when it's simple to do so[you can also browse through and notice how much of that came from commercial companies such as Nokia, Samsung, and Texas Instruments...that's due to the big market for Android phones which are based on Linux and use the Arm processors.  If you want YOUR chip to be used in the next big phone, you make a point of provided all that code and documentation so it's readily available.]

So...as long as it's simple and I can do it with the same patch request, sure.  Make me jump through hoops and I'm not really interested.

[Gary Mort]

On Sunday, November 10, 2013 6:12:50 PM UTC-5, Gary Mort wrote:

So...as long as it's simple and I can do it with the same patch request, sure.  Make me jump through hoops and I'm not really interested.

BTW, it seems to me that the rule of thumb for Linux Documentation is as follows:

If it is a new feature that is a subset of other features, it's accepted with or without documentation

If it is a /change/ to a feature than it should be documented.

So for device tree, for example, the base documentation, device-tree.txt already existed.  Because they want people to switch to using them because it makes code maintainable, there were a lot of initial patches which just referenced the generic doc that already existed - which is fine.

Then when they came back and wanted to make some tweaks after finding problems, changes to the API required docs[since it's not really fair to expect other programmers to guess at what you changed...  while they could be expected to read the code to find out what the initial features were - changes must be documented.

It makes for very quick documentation cycles on new features as their being tweaked.   On the downside, there are some features that go in almost perfectly and then never get documented...[I'm still poking away at the USB media stream gadget to figure out how to mod it]

-Gary  

[Andrew Eddie]

On 11 November 2013 09:12, Gary Mort <jooml...@gary.mort.net> wrote:
> IE new feature for the CMS
> plugin/editors/raptor <--- adds the Raptor editor as an option for the CMS
> MUST be accompanied by
> docs/editors/raptor.??? <-- documents some of the options available on the
> raptor editor plugin
>
> The problem is, that to require it, you will need to decide on a system to
> use for documentation. IE how to embed external links to the Joomla Doc
> pages, how to cross link documentation, etc. Do you want it as text
> information, html, markdown, something else?

I've gone through so many iterations on documentation it's not funny,
and my current stance is "I don't care" what format it's in, whatever
is the easiest for "you" so long as we can find it (and as long as
you've made an effort). It could also be as simple as a heading and a
few paragraphs in the PR itself. I personally think everyone should be
able to tool up on markdown because in the worse case, it's just a
text file anyway and that is the lowest common denominator. I agree,
media is an issue but Github allows drag and drop images at least.

Regards,
Andrew Eddie

[Gary Mort]

On Sunday, November 10, 2013 7:02:59 PM UTC-5, Andrew Eddie wrote:

On 11 November 2013 09:12, Gary Mort <jooml...@gary.mort.net> wrote:
> IE new feature for the CMS
> plugin/editors/raptor  <--- adds the Raptor editor as an option for the CMS
> MUST be accompanied by
> docs/editors/raptor.???  <-- documents some of the options available on the
> raptor editor plugin
>
> The problem is, that to require it, you will need to decide on a system to
> use for documentation.  IE how to embed external links to the Joomla Doc
> pages, how to cross link documentation, etc.  Do you want it as text
> information, html, markdown, something else?

I've gone through so many iterations on documentation it's not funny,
and my current stance is "I don't care" what format it's in, whatever
is the easiest for "you" so long as we can find it (and as long as
you've made an effort). It could also be as simple as a heading and a
few paragraphs in the PR itself.

I'm perfectly fine with that.  If I'm able to stick it in my pull request somehow, either as a file in the request itself, then I have no problem with needing to include documentation of some sort.

[Mark Dexter]

That seems workable to me. The minimum should be to get enough information in there for (a) people to test and (b) docs folks to work with. The emphasis should be on raw content, taking into account that the dev may not be great at documentation or great at English.

--

[Andrew Eddie]

Can we agree, then, on the following "principles" to apply across the
board for all code we manage (CMS, Framework, whatever):

1. Pull requests with code MUST include full API documentation. In the
case of PHP files, this requirement is deemed to be met if the code
passes the automated code-style checking against the Joomla Coding
Standards.

2. Contributors MUST make a reasonable effort to include end-user
documentation for new features or changed behaviour whether that
applies to a UI or the code API. End-user documentation can be
submitted in any textual form, or link thereto, provided appropriate
permissions have been granted to use the content.

How say you "in principle"?

Regards,
Andrew Eddie

[George Wilson]

I'd add if there are UI changes people MUST update the help screens

Kind Regards,

George

[Mark Dexter]

I agree with the sentiment but I don't think it's at all realistic. I'd rather have a great new feature and play catch-up on help (the way we and many other projects have always done) than forego or delay a great feature. My .02. Mark

--

[Andrew Eddie]

On 12 November 2013 01:15, Mark Dexter <dexter...@gmail.com> wrote:
> I agree with the sentiment but I don't think it's at all realistic. I'd
> rather have a great new feature and play catch-up on help (the way we and
> many other projects have always done) than forego or delay a great feature.

But we've never, ever caught up. We are, however, not going backward
on the Framework because we have this rule and *nobody* has ever
complained when asked "hey, would you mind doing up a page on how to
use this class and here's an example for you to follow". On top of
that, we have a culture in this project of wanting to attract traffic
to our own sites and sell books (we have plenty of people that want to
write documentation, just not on property). People test patches don't
they? Why is it any different for documentation? Because we are too
scared to ask in the first place.

Anyway, I've put up an unofficial vote here:

https://github.com/joomla/joomla-cms/issues/2496

Let's test the waters and just get this done.

Regards,
Andrew Eddie

[Mark Dexter]

I don't think you can reasonably compare the Framework to the CMS with respect to docs. Does the Framework have help screens? Personally, I would rather have a dynamic project with new features and have the docs lagging vs. discourage new feature contributions. But that's just my .02. Mark

[El KuKu]

Hell YES !

I don't think that it's too much to ask, and once you get used to it, it's actually fun making some words about the code you just wrote.

I don't know what I would've done with the new toy DIC without any documentation on how it's supposed to work... (Thanks Don)

I also think markdown in combination with GitHub is a great way to write documentation in a collaborative way. See: http://symfony.com/doc/current/book/index.html note the "Edit" button!

[Matt Thomas]

In my opinion, it would be great to require it, but I'm not sure if we should or can. I personally need some time to weigh the pros and cons.

That said, having documentation to accompany a proposed feature is certainly good way to help its acceptance. If a newly proposed feature isn't easily understood without it, I can see that as a valid reason for not accepting it.

That is just my opinion.

Best,

Matt Thomas
Founder betweenbrain™
Lead Developer Construct Template Development Framework
Phone: 203.632.9322
Twitter: @betweenbrain
Github: https://github.com/betweenbrain

Sent from mobile. Please excuse any typos and brevity.

--

[Andrew Eddie]

On 12 November 2013 08:04, Mark Dexter <dexter...@gmail.com> wrote:
> I don't think you can reasonably compare the Framework to the CMS with
> respect to docs.

You absolutely can.

> Does the Framework have help screens?

Yes it does. The tutorials on how to use the API are no less import,
nor take any less effort - more in some case. Here are a few examples:

https://github.com/joomla/joomla-framework/blob/staging/src/Joomla/DI/README.md
https://github.com/joomla/joomla-framework/blob/staging/src/Joomla/Cache/README.md

Here's an example of what we'd consider "basic" but obviously could do
with a lot more work:

https://github.com/joomla/joomla-framework/blob/staging/src/Joomla/Facebook/README.md

Those README files are the end-user equivalent for the CMS's help
screen. They take a lot of work and we appreciate the effort put into
them.

The Framework and Platform before it have asked for documentation with
PR's from day one. I've never had anyone throw a hissy fit over being
asked to write some notes about their feature.

Regards,
Andrew Eddie

[Andrew Eddie]

I just want to respond to some of the -1's but not in the voting thread.

Nils, yes, changes to the wrokflow would go hand in hand with this
proposal. This is a workflow step.

Quoting Beat:

>>>
So while warmly welcoming documentation in general, for that question
on the CMS repository, I clearly give a :-1: 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.
<<<

Point 1: Bias is everywhere. What do you think it biased?

Point 2: The rule is actually already in place in the Development
Strategy, this is just clarifying and guiding how it will be enforced.

Point 3: Improving the workflow will not magically coax people into
writing documentation but changes to workflow are definitely required
and this will make it easier all round

Point 4: We aren't asking for people to be good doc writers. We are
asking them to make an effort. Watch
http://www.youtube.com/watch?v=p8ft_H_wymU&feature=c4-overview-vl&list=PL0Lg2fzcJu1T4_QwkOu4tbUHs2f6y2NMh
starting at 39:00 QED

Point 5: I'm of the opinion that gradual improvement hasn't worked so
well for us so far?

Point 6: Well yes and no but we don't have any workflow for picking up
features that aren't documented so there is a hole in the system. This
will fix it definitively and I am absolutely convinced the push back
will be minimal. It's time to improve our game if we are serious about
quality.

A vote for this is a vote for providing the best service to our users.
Just google "Content Revisions Joomla 3.2" and you will find every
man and his dog grappling for the #1 SEO position. The content writers
are out there - let's just make sure the community good comes first
before site traffic.

Regards,
Andrew Eddie

[Mark Dexter]

There are two separate issues here. The first issue is whether we value documentation. The second issue is whether we need or want hard-and-fast rules about this. Generally I am against hard-and-fast rules. They usually cause more problems than they fix. 

I think it's great if the PLT and others want to factor in the presence or absence of docs when weighing the benefits of a proposed feature. If they want to say "This feature is great but we won't accept until it is better documented" I think that's fine. But I don't see the value in trying to codify this into a rule. If we say we "require" docs, who decides if the docs are good enough? We're right back to a subjective judgement, which sort of defeats the purpose of a rule.

I think docs are very important and have spent more than my share of time working on them. I am one of the small number of people who have contributed a significant number of help screens in the wiki. And I did help screens and a dev doc for content history feature, but only after the feature was accepted and committed. (Good thing too, since we had last-minute changes to it -- which of course is normal.) 

To me this is not at all about the value or benefit of docs. It is about the value of hard-and-fast rules. No one disputes the former-- it's the latter that we disagree on.

Mark

[Andrew Eddie]

The counter points are that "tests must pass" is a hard and fast rule.
Code-style must be maintained is a solid rule. Not everyone has
permission to merge code is a hard and fast rule.

We don't play catch up on PR testing (the alternative is blindly merge
it and let someone find the problem in production). We are playing
catch up for code-style for a number of very good reasons, and people
are getting used to it. Documentation is no different and the users
and I'm sure the other teams will welcome the decision. 3.2 is out
there and the help screens aren't finished. Is that really good
enough? No, and the root of that problem comes from not requiring
documentation with pull requests (it is trivial to prove beyond a
doubt that there are people out there who can and will write the
documentation).

I understand some people are afraid of change, but as I've said, the
Framework team, mavericks that we are, have already tried and tested
the requirement for several years and it has not been a problem. Our
contributors are only too happy to provide it. Those contributors
happen to be some of the same people that contribute to the CMS. Ergo,
it's not going to be a problem :) We are still catching up, but we are
not as far behind as we could have been.

Regards,
Andrew Eddie

> You received this message because you are subscribed to a topic in the

> Google Groups "Joomla! CMS Development" group.

> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/joomla-dev-cms/llT8RQgRzeA/unsubscribe.
> To unsubscribe from this group and all of its topics, send an email to

[George Wilson]

Let's be honest - no one wants to do docs. JWC13 had 1 person turn up to the docs session ;) - and I personally think the most likely thing to happen is we're going to discourage people from contributing to the features than we are to get people start doing docs. The 2.5 help screens only got finished 3 months ago (or so) - so yeah clearly the 3.x are going to lag as well. If anyone wants to help me and Tom with them that would be awesome (thanks to mark for his major contributions here) but I'm not going to be holding my breath. We also need to fix 50% of the ones we've already done cause of the UX changes.

I think its so much better to have one more person join a team than have 20 people have half-assed efforts to write stuff for their feature. I'm more with Matt - if the docs aren't clear enough on feature submission we can reject it. But it things are clear enough for the feature to be accepted then let it through. It would be the CMS's loss.

Kind Regards,
George

[Donald Gilbert]

Having a low barrier to entry isn't always a good thing, as it lets in rodents and bugs. :P

Raising the bar ever so slightly can greatly increase the quality of the code being submitted, as it requires the submitter to at least have some sort of frame of mind and thought organization for contributing. Without being able to explain your PR (with or without help, it matters not), then I would question the validity of the code being contributed in the first place.

If you have time to write a feature, you should have time to write documentation for it.

Quality > Quantity, we've tried it the other way long enough, IMO.

Final note, I'm not saying you need documentation before ever submitting a PR, just have in mind that you'll need to be able to explain the code before it gets merged. It just makes sense. I'm also not saying that YOU, the PR submitter, need write the documentation, just that it should be present so that the code you're submitting is used in the way intended. This helps to solidify exactly what is meant to be the public API and how exactly it should be used, which makes it MUCH easier maintaining in the long run.

[Donald Gilbert]

I would argue that, given an ideal situation, we would never even entertain the thought of merging code without understanding how it works.

People can search through open issues and add documentation for those features they care about, since without it they can't get it merged. It helps promote ownership and "skin in the game" so to speak to have to put in a little extra effort in order to see a PR accepted, rather than just "here's some code, merge it without even me understanding what it does"

[Donald Gilbert]

"We have all these great new features that no one knows how to use!! Don't you love Joomla now!?!"

Sorry, I don't buy that.

[Donald Gilbert]

No one wants to do docs because they aren't the ones who wrote the code. The hands down best person to write the docs (at least the outline and general direction) is the person who wrote the code in question. Do you disagree?

[Tom Hutchison]

I've gone through and read every post so I thought I'd add my thoughts on this thread as the PLT member who is responsible for documentation.

First, docs is already part of the development strategy. 

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

To maintain features and systems added to the code base, as well as to help ensure an ability to uphold our principle of backward compatibility some basic documentation is required for new API classes and methods or new application logic when it is added to the trunk. If you are writing a new class or method, describe what it is supposed to be used for and why it exists and a couple of brief examples of its use. For application features, describe the addition or describe each layout and their intended purpose.

The above can be found at http://developer.joomla.org/cms/development-strategy.html

The devil is in the details along with the word, basic. ;)  Define the word basic.  From my point of view and many others, we do not need the next Pulitzer prize or best-seller list piece of documentation. Any contributor to the core who steps up and really want to contribute a new feature to it should at least have a basic, outline - framework, and let me shout this, A PLAN. Something written showing what the contribution is envisioned as in an end product and how they are going to get there. The new feature, what exactly will it do, classes, etc.

Will this slow contributions? Perhaps. Do we want quantity or quality? I personally want quality and I want to tell others we have a quality CMS.

If we give the contributor the tools to ask for doc help, same to or similar as asking for testers and work it into an issue tracker it should do a few things (I hope). First, if the contributor is asking for help, let's see if we can help them. Maybe they have a great feature and just can't explain it, a language barrier, etc. Second, many of the contributors like using markdown on GitHub. Let those developers willing to help other developers in need use their preferred or familiar syntax. There are a large number of converters which will take markdown and change it into just about any syntax. 

Ideally, CMS stuff should live in our real docs, but the world isn't always ideal and I expect a reasonable lag. By reasonable, I mean a few weeks or month to catch up. IMO, the feature isn't complete until it is doc'd. It's the same as buying a television, told about all its features. Manual?  Just play around with it, you'll figure it out - eventually.

To be clear, asking for help, should not be a crutch for the lazy. No one wants to do another developer's docs when the other developer didn't even bother to start docs themselves. I just want to code and I can do it in my head, piece this and that together and then say, help me do a doc. Chances are the code probably works, but badly because they lacked a plan of how to get from A to B. I wouldn't want these features merged in anyway personally. IMO we also shouldn't merge feature 2 from the same contributor if they still haven't doc'd feature 1.

Yes, no one wants to do documentation but yet complain they don't exist but do nothing about it. If we do not change our current culture, we will be having this conversation tomorrow, next week, next year and the year after and so on. Docs should be the responsibility of everyone, which I mean in the sense we should police ourselves. I'm testing your feature, let me read about it too. You don't have the docs for it? Ask why not.

Dealing with all the UX changes, it was suggested in the spring we should be able to script and take a snapshot of all the admin views. That would be a tremendous help if we could make this a reality.

Hopefully we can move forward, thanks for reading.

Tom Hutchison

PLT member

Documentation

[Donald Gilbert]

++++10000

Tom, you've explained my feelings on the matter exactly. This is what we should do.

Thanks,

Don Gilbert

[Dmitry Rekun]

+1 goes to Tom Hutchison :)

Dmitry

[Chris Davenport]

Personally I believe that documentation is something that should be done continuously throughout the life cycle of a feature.  The documentation should evolve along with the code.  I know that a lot (most?) developers hate writing documentation and many (most?) are rubbish at it too, but some of us, like me, actually enjoy writing documentation.  I actually find that I write better code if I write the docs at the same time.  Writing docs helps to clarify in my mind what the code needs to do.  Documentation that is written alongside the code becomes part specification, part design scratch-pad, part test template as well as forming the bulk of the finished documentation.

I think some level of documentation should be required for all new features, although we can set the bar pretty low to begin with.  What I think we should do is encourage individual developers and working groups to ask for assistance with documentation at an early stage if they feel they do not have the skills or enthusiasm to do it themselves.  Having documentors working alongside coders can bring similar benefits to having testers working alongside coders: you end up with a better quality product with fewer bugs and which is easier to use by its target audience (be they end-users or other developers).

Chris.

On 10 Nov 2013 10:17, "Valentin Despa" <in...@vdespa.de> wrote:

I find contributing to the documentation (where there is no stub for a topic) very hard.

I would propose to have at least a basic page for each new feature (title, properly organised in a category) where at a later other people can contribute with content.

--