Documentation

[eddieajau]

How do we move the help screens from docs.joomla.org to this repository?

[wilsonge]

The entire help screen software runs on J1.5. It needs updating (something I've been meaning to ask to see if we can upgrade). I'm not sure it's gonna be easy to move from Joomla Docs at all without doing substantial modifications to the software from what I've understood from Tom.

[eddieajau]

Would someone mind contacting Tom and Chris to see what their thoughts are. I'd personally like to conduct an experiment with Github pages.

[mbabker]

Ping @chrisdavenport and @Hutchy68 :smile:

[phproberto]

My vote goes to docs folder on the repo. New feature = documentation required to be accepted. In fact is the perfect place to play with it before trying it on a large scale on the CMS.

[eddieajau]

Roberto, that's my preferred view as well.

[wilsonge]

So how do you expect GitHub to deal with translating documentation? - that would be my biggest concern

[eddieajau]

So how do you expect GitHub to deal with translating documentation?

Storage wise, we can do /docs/en-GB/... and so on. Publishing wise, I still have an experiment planned to use gh-pages but I haven't had time to get there. Some major decision recently got in the way ;)

[wilsonge]

Also for help screens don't forget about this https://github.com/joomla/joomla-cms/pull/3351

[eddieajau]

Can you give me the executive summary of what that's trying to achieve?

[wilsonge]

It automatically creates help screens from the form fields (irrespective of language theoretically - haven't tested myself practically - I'd need to talk to Mark but may need per langauge tweaks) takes screenshots and uploads them to the wiki via Selenium

[eddieajau]

Ok. The ideal would be for such a tool to be used by any extension developer, and if so, that would solve the problem for us.

[Hutchy68]

The help screens are tied into two methods. One, they can be served locally. Two, they can be served remotely. Basically, it's just a matter of adding the appropriate line to the xml help screen control file to enable the drop down menu in configurations to choose where to look for help screens, locally or remotely. The remote part, which we "hard set" by removing the local line of xml for choice is through a J1.5 help server proxy. Runs a custom component, @chisdavenport can fill in more on this. I have no access to this server.

Last year, we discovered old help screens(more of place holders) for 1.7(I think) buried in the /administrator folder and long forgotten. We eliminated them, but in the process broke the TOC because their titles were tied to the formation of the TOC for the main help screen navigation page. @mbabker did a fixed this with a PR to use doc's api to dynamically grab a TOC. That went into 3.2.1(memory) to fix what was broken in 3.2 release.

The whole system was written so a site builder could use default, their own hard coded files or their own remote system. There is also a mechanism for extension devs to add their own files for help screens. Partly why the old files were still hanging around. Everything is connected.

Mark wrote the Selenium/automated help screen generator. Basically, it snaps a screenshot of the admin view and builds a text file of the form fields on a screen and their descriptions. For other languages, if the language files are installed, it will automatically grab a lang specific screenshot and the translated form fields and descriptions when set to the lang. The automated part, the generated files can be uploaded in 5 mins or less with a script. Done, you have help screens. Long term, the goal is to show the help screens automated, with a link or links for a more "how to" based doc on the specific help screen. Those how to docs can be translated on docs and this way everything is integrated.

The current system is no more than a regurgitation of the screen the user is already looking at, so what is the benefit? So an article view how to would be, give your article a name, now an alias, pick a category to place it in, type content in the WYSIWYG editor, use this to do that, etc..etc...

I and other have been working to improve help screens and make them useful. Tracking down missing keys and adding them, working out what was broken and fixing it. So, before we even get into all of this. There are several issues to be addressed first. I'll start with just a couple.

1. Automated screens, great. Will the core maintainers maintain them? Generate and upload them.
2. Probably should mention, they aren't fully automated. What do I mean by that? No form fields on a page, no text. So there will still be a need for humans to doc those screens. Devs?
3. Are the devs now saying they want to write and maintain end user docs too? The help screens are end user and you would be asking a non dev end user to submit a PR for help screens. A translator to submit a PR for their help screens. Honestly, good luck.

[eddieajau]

Thanks @Hutchy68

Automated screens, great. Will the core maintainers maintain them? Generate and upload them

Nothing will change for the core CMS. The question is as we are decoupling extensions, should all documentation reside locally in this repository.

Probably should mention, they aren't fully automated. What do I mean by that? No form fields on a page, no text. So there will still be a need for humans to doc those screens. Devs?

I don't see this as a problem. Any extension developer knows that you can only automate so much and there are things that are just not contained in forms. Documentation requires human intervention.

Are the devs now saying they want to write and maintain end user docs too?

I'm not sure who "the devs" are but I'm asking the question about maintaining documentation for community supported extensions in this repository.

The help screens are end user and you would be asking a non dev end user to submit a PR for help screens.

Developers can submit PR's too.

A translator to submit a PR for their help screens. Honestly, good luck.

Some would say the same thing about using Joomla itself. If you can work out how to link content to a menu and then have modules selectively appear on various pages, you are more than qualified to use Github.

[chrisdavenport]

What would you gain by moving the help screens to GitHub? What problem are you trying to solve?

[eddieajau]

What would you gain by moving the help screens to GitHub?

Potential gains are the everything to do with the extension is in one location: code, tests, documentation - a one-stop-shop if you like. Further, you can tightly couple the addition of documentation with the addition of code and that solves a few problems we have today such as help screens not being ready when a new version ships. The markdown format is also easy to learn and well supported.

What problem are you trying to solve?

Well, the overarching problem we are solving is to lighten the load of the core CMS as directed by the PLT announcement, and remove things that aren't considered absolutely necessary for each site. Therefore, as we are moving the code to a new repository, and decoupling the build and release processes (that is, Weblinks more or less becomes like a third-party application), it's appropriate, I think, to ask the question, well what about the docs? So I'm asking the question is there any reason why they can't go in Github so that everything is in the one place?

Since we are only dealing with one extension, it seems an ideal time to conduct an experiment to see if we can make it work. I honestly don't know if it will or won't, but not trying doesn't not give us any data by which to assess the question :)

[infograf768]

We are dealing —today— with one extension, but what will happen when we have more "core supported" extensions? Who is going to "tightly couple" docs with code?

I agree with @Hutchy68 remarks and I do not think your reply is realistic. Specially concerning Translators using github.

[eddieajau]

but what will happen when we have more "core supported" extensions

Each package (group of extensions) will have its own repository like this one.

Who is going to "tightly couple" docs with code?

The idea there is that a Pull Request comes with both code changes and documentation for those changes. The reality is that a good test plan for a change is more or less your documentation anyway. Let's say a new view is added, then the code and the help screens for that view will have to come with the Pull Request. In other words, this forces the contributor to run around and organise documentation if they cannot do it themselves (which could include liaising heavily with the documentation team) rather than expecting the documentation fairy to do it for them.

[eddieajau]

As for translation, you would have a set of English markdown files that could be fed into any of the "tools" currently available for translation. It doesn't matter to me which one you use, or if you just use an editor to do it. I don't know how people translate MediaWiki entries but I can't imagine translating a markdown file being any harder.

[infograf768]

The point is that after years of looking for solutions, Tom, Mark and Chris have only very recently proposed a relatively easy way (with some automated tasks specially concerning screenshots in the correct language) to get help for some languages from the wiki. (Hard for me as you know because of wiki, but nevertheless we do have volunteers working on this right now)

Looks like you are throwing the just born new baby in the pond.

I also do not see how you would update and display the help when only an aspect is taken care of in the PR. For example let's take Global configuration where we recently added the Proxy parameters. The help for that should display with all the help for Global Config.

[eddieajau]

I also do not see how you would update and display the help

I have some ideas.

[eddieajau]

Looks like you are throwing the just born new baby in the pond.

Just to clarify, the core help would not change so nothing is lost.

@Hutchy68 and @chrisdavenport, if we were to continue to use the wiki to support documentation, and the number of these Extra extensions shoots into the dozens, each carving their own development path within each major CMS release, and potentially having different teams supporting them, how do you see that working (or your coping) in a decentralised environment (compared to the current monolithic system - one CMS, one large team, one release at a time)?

[javigomez]

The big benefit of the current translation system in mediawiki is that you do not translate the entire document but pieces of it (paragraphs). This pieces are linked in between the different languages. If someone does a change in en-GB, all other translators can see a warning, and you can see specifically witch part was changed.

I see git (and Github pages) has nearly the same possibilities because it informs exactly witch line was modified but we still will have to build something that links the lines in between the different languages.

[eddieajau]

Can you link me to an example?

[chrisdavenport]

The help system is agnostic about what it is that is serving the help screens. It can be the local file system, a Joomla instance, a MediaWiki instance, Github pages or your uncle's toaster; it doesn't care. You simply pass it a URL and it renders it in a popup window.

That's why I asked what problem we are trying to solve here, because it surely isn't anything to do with what is actually serving the help screens.

I think we should start from a different angle and consider what we want to achieve with a "help system" generally. Let's ask ourselves questions like what is it supposed to do and is there a better way of doing it.

Currently in Joomla we have two ways of accessing help information: clicking on a help button and going to the consolidated help (ie. Help -> Joomla Help). Both make a lot of sense and I think both should be retained. However, the way we currently do them is probably not where we really want to be.

I think that help information should primarily be organised in a "goal-directed" fashion, so that users navigate the information by starting with a high-level goal (eg. "I want to create a new web page") which can then be broken down into sub-goals and specific individual tasks (eg. click this or enter that). So what I'd like to see with the consolidated help is something along the lines of a top-level directory of possible goals with a variety of methods, including full-text search, of finding the "goal tree" that addresses a users needs at a particular moment.

The help screens accessed from individual pages should, in my opinion, be less a description of what is on each page and more an entry point into the documentation's goal tree. The help button is a hint to the help system about what information the user might be looking for and we should use that context information to prune the goal tree appropriately.

Now, assuming you agree with this vision of an ideal help system, we then have to figure out how to make it work in the context of a modular, multi-lingual CMS where the user might have uninstalled extensions that the documentation refers to, or installed new ones that it doesn't; where the documentation may be spread over multiple websites running on arbitrary platforms; where each page might contain rich media types, such as embedded videos or sound clips; where not all documentation pages are available in all languages and where tools to support the creation and maintenance of the documentation are still far from ideal.

The approach that we have been pursuing for many years is to try to break the documentation into appropriately sized fragments (chunks) that can be assembled into larger pieces and re-used in different contexts. I think that approach will also help with the lightweight core concept for the CMS too. For now, I think that it is better to have a single repository for those documentation fragments because it makes re-use (via linking or transclusion) simpler. That will probably need to change eventually but I don't have a clear picture of how we would make a truly distributed, modular documentation system work right now.

But I don't see a compelling reason to move to GitHub at the moment. We would need to do work to re-host part of the documentation which would make transclusion harder and we would end up with a weaker set of tools than we already have. I think that moving help screens or any other user documentation to Github at the moment would be a waste of time. What we need to focus on is designing and building a modular help system which continues to be agnostic as to the platform that is hosting each fragment. Solve that problem first and then we can decide which platform(s) we actually want to host it on.

[eddieajau]

I think the issue is a difference in perspective. I'm looking at decoupled extensions as moving towards how third-party extensions need to be managed. I think you're focusing on the mindset that Weblinks is still a Joomla CMS extensions but it's just optional. Can the PLT let me know which mindset should be used (aka innovate or status quo). If the later, the project is virtually finished.

[wilsonge]

Just as a 3PD here I'd never use GitHub for documentation or translations :P I'd call github a bail out for documentation - as it's UI to me isn't as intuitive as a wiki for people who aren't already familiar with GitHub (I'm sure others will disagree but that's my opinion). Also so many people will have made an edit here and there on wikipedia in the past and will be used to how that works (or maybe thats just my young ago coming through :P)

Also let's me honest for a given 3rd party extension - it's not going to get a huge amount of extra features. Maybe a buff or two here and there. But how many of our components have had significant new features since the rewrite of 1.6?? (And by components I don't mean the core core stuff like com_config and com_templates but more the stuff we're looking to separate here). And so to my mind it's not like developers are ever going to be needing to write large amounts of documentation so with that GitHub looses some of it's appeal

[eddieajau]

Also let's me honest for a given 3rd party extension - it's not going to get a huge amount of extra features.

No, Weblinks is not and I'm not under any delusion it is. However, I think we have an opportunity to solve some real problems that face 3PD's (let's walk in their shoes for a while), and having experienced the issues they face, we might be able to present them with a pattern that works and they can learn from.

But if the exercise is literally to just move PHP files out of /joomla/joomla-cms and into this repository - jobs finished.

[chrisdavenport]

@eddieajau I think you're missing the point I was rather clumsily trying to make. When a third-party extension is installed it needs to integrate seamlessly into the CMS. That should apply to the documentation as well as the code. Where the documentation is hosted should be irrelevant and developers should be free to choose whatever platform they prefer. What we need to work on is making the integration of third-party documentation as seamless as installing the extension itself.

[eddieajau]

Right. But my point is I want to "have a go" at including all the docs, including help screens in the repository and seeing how people respond to Github and Markdown (we've trained our Framework contributors to do it, CMS users will be a piece of cake). If it doesn't work we'll have learned something. But if the decision is, no, even for decoupled core extensions we must use MediaWiki for help then that's fine and it's decided and the job is basically finished.

[eddieajau]

The reason for "having a go" is to tightly integrate the contribution of coded features with the documentation before merging and being able to do it in one location. Our system currently falls down because the CMS does not enforce that documentation should be finished when code is contributed.

[infograf768]

I have the feeling more and more, whether concerning the docs or the discussion here https://github.com/joomla-extensions/weblinks/issues/2 that some people do not consider anymore "decoupled extensions" or "core supported extensions" as under the responsibility of Core, whether concerning languages, help, support or upgrade.

This bothers me.

[eddieajau]

@infograf768 you are absolutely right. I'm interpreting the request from the PLT as "treat Weblinks like a third party extension, only Joomla is hosting the resources". If that is a mistaken assumption, I'm certainly wasting both yours and my time trying to think about process and product improvements (in fact, I'd then argue taking Weblinks out of core is a complete waste of time).

[infograf768]

In the case of weblinks, it's simple to understand: backward compatibility (as defined in the new development strategy) cannot be broken

[eddieajau]

@infograf768 it has absolutely nothing whatsoever to do with backward compatibility. Changing a "process" does not stop PHP code from working. If it does, that's called "magic".

[infograf768]

Language is part of B/C

[eddieajau]

Documentation isn't. Wrong thread perhaps?

[Hutchy68]

@chrisdavenport, thanks, agnostic is the word perfect for the description of what we have now. What is available to 3PD is already very flexible. As a 3PD you can do a a couple of things. Right from docs:

If help screens are included in the extension installation then the second argument to JToolBarHelper::help should be set to true. For example, to force the use of local component help files, use code like this:

JToolBarHelper::help( 'MY_COMPONENT_HELP_VIEW_TYPE1', true );

This call will look for the language key MY_COMPONENT_HELP_VIEW_TYPE1 and use the value found, if any, to construct a local file path to the help file. For example, if the component language file /language/en-GB/en-GB.com_my_component.ini contains the key-value pair

MY_COMPONENT_HELP_VIEW_TYPE1="view_type1"

then the file path constructed will be

/components/com_my_component/help/en-GB/view_type1.html

Remote help for a 3PD extension on your own server

$help_url  = 'http://www.example.com/{language}/help-server';
JToolBarHelper::help( 'MY_COMPONENT_HELP_VIEW_TYPE1', false, $help_url );

Changing the location of where to point help buttons should be easy. Just change the point at location for the weblinks help button, done.

@eddieajau, I understand what you are trying say and your concerns about decoupling and maintaining docs, several core extensions, etc... but as Chris pointed out we have two entry points to help screens. Direct from admin view and direct on docs. Screenshots was one of the most painful tasks for the direct on docs views, which was the inspiration for automation, solved. Addressing the other aspect, @chrisdavenport said 'goals,' I used 'How to's" which I consider the same, just British vs. American terms. Using transclusion to build modular docs with top-level docs, from pieces of lower level information is currently what we are doing now. We just need to keep working on improving them.

The big issue to take into account is fragmentation of docs. So let's say weblinks help screen docs are now hosted by Github. Links to more information, goals(how to's) pointing where? Back to docs.joomla.org? Another page on gh-pages? Entry point for docs not in admin view to weblinks? Where is that at? Would we have to build all user docs and maintain them on GitHub eventually? This puts the project on the end user docs road to GitHub, IMO and that's a waste of time because...

The even bigger issue is added dependency for end users of the CMS using GitHub to maintain these docs. Reason I asked if the devs or core maintainers would take up maintaining the docs? Because to think a CMS end user will use GitHub to maintain them is wishful thinking. It just won't happen and for a developer who is comfortable with GitHub to say it would be easy for a non-dev is not basing their statements on a realistic view of the actual workflow and methods to create documentation on GitHub. Work through 10 PRs to correct the spelling of two words and comma placement on the weblinks help screen or eventually a "How to Add an Article" page. It doesn't make sense.

I can see where the a lot of developers see docs on GitHub and associate GitHub as a great place to write documentation. Upon closer inspection, the vast majority of them are developer docs geared towards development. Frameworks, plugins, you name it, they all contain

Code blocks

with instructions on how to integrate their project's code into yours. These are not end user docs. They are like our Framework docs, very well done but specific to a developer using a framework.

Only end user docs... true end user docs, have no code, no code blocks...no this is how you integrate this into your web pages, html... I could find was for phpBB Forum, with the last PR to their documentation 5 months ago. Pretty stable docs, are we at that point no. gh-Pages used by them, I don't think so and what is in their repo is light compared to what they have online.

Let's get weblinks decoupled first, and hold off on applying the Winchester Mansion model to documentation.

[eddieajau]

So @mbabker is saying "have a go" and you guys are saying "don't rock the apple cart". Which is it? I just don't want to waste my time pushing for innovation and invention if your minds are already made up before the journey has even started.

Let's get weblinks decoupled first, and hold off on applying the Winchester Mansion model to documentation.

If "parts" of the decoupling are off limits, there's not much point. I think the PLT needs to sort out what's in and out of scope because it doesn't sound like you guys are collectively on the same page at all.

[wilsonge]

1. Is changing the mechanism for end-user and developer documentation
and help screens within the scope of decoupling?

Initially, I would say no.  I'd personally rather focus on dealing with getting the code out of the main distro and working out the logistics of maintaining it as a separate extension before moving on to areas such as documentation.

(Source: https://groups.google.com/d/msg/joomla-dev-cms/_QeFxkf8W08/coTOPRzZdBoJ) I can't speak for Michael but that doesn't sound like "have a go" :P

[eddieajau]

@wilsonge sorry, reading email in non-chronological order.

[wilsonge]

lol no worries :) been there done that before!

On 10 April 2014 22:58, Andrew Eddie notifications@github.com wrote:

@wilsonge https://github.com/wilsonge sorry, reading email in non-chronological order.

Reply to this email directly or view it on GitHubhttps://github.com/joomla-extensions/weblinks/issues/3#issuecomment-40148119 .

[eddieajau]

These are not end user docs. They are like our Framework docs, very well done but specific to a developer using a framework.

So basically you need to see proof first before you will believe? If I give you the proof, will you agree to at least consider the possibility and negotiate?

[eddieajau]

Links to more information, goals(how to's) pointing where? Back to docs.joomla.org?

If there is any useful material on docs.j.org that can be linked to, you'd link to it. That's what 3PD's already do. But information pertaining to just this extension can be hosted using gh-pages and that would include help screens, end-user tutorial documentation and developer notes. gh-pages is just a static web site (with benefits) so there is no limit to what you can achieve.

Because to think a CMS end user will use GitHub to maintain them is wishful thinking.

We have CMS end users making edits to CMS files today. The process is actually easier than publishing an article in Joomla in some cases.

[eddieajau]

@chrisdavenport and @Hutchy68 - how about this. Do I have your permission to get a team of people to conduct an experiment to host all help information for this extension in gh-pages (which means scraping content from the wiki)? We can then evaluate it against the existing system and make a decision on which is the better way to move forward? If you don't agree with the final product, nothing will be lost because I'm sure some 3PD's will still be interested in the system.

[wilsonge]

So to me with github you'd need to prove two important things 1) It doesn't adversely affect end user contributions (as we'll want to promote users to show how they use the extension in some weird but wonderful way) 2) We can deal with the translating of the docs as easily as we can with the mediawiki

Also my final thing is a new feature gets merged in but the docs will show for that new feature regardless of whether it's actually in the latest version of the component or not? How are we dealing with that - because I assume we're using the github wiki rather than writing files in markdown (which is really not end-user friendly viewing imo)

[chrisdavenport]

Why would you need our permission? Anyway, we already know it's possible to host the help pages on Github because the help system was designed to make it possible to host the help screens anywhere. That's never been in doubt and doesn't need any experimentation to prove it. Plenty of third-party developers already have working help systems on a variety of platforms and use the existing help system API to achieve it.

The question is do we actually want to do it for a decoupled weblinks? What do we gain by moving the help screens to Github? If the developers were the ones writing the user documentation then we might gain something by having code and documentation in one place, but it's rare for developers to be able to write decent user documentation. By moving code and documentation into a single location for the benefit of those developers who probably won't be the ones writing the docs anyway, we hinder the work of the documentors who will be doing the work by fragmenting the material across different platforms, one of which (Github) is less suited to the task than their current home.

We might pretend that we're third-party developers with regards to weblinks, but at the end of the day it is still an officially supported extension and if we're going to continue to support it then it needs to fit in with needs of the people who will be looking after it. I'm all in favour of hosting the code on Github, but I can see nothing but unnecessary pain in moving the documentation to Github too.

You seem to think that the answer to every problem is Github, whereas I believe we should use the tool that best matches the needs of the people who will work on each particular aspect of it. Now, if you were to suggest building an "ideal" documentation platform which happens to use Github as a repository, similar to how JTracker adds or compensates for deficiencies in Github's issue tracking capabilities, then you have my attention. MediaWiki is not without its downsides after all.

There are important challenges to be faced in working out how to integrate documentation for decoupled extensions. Moving the help screens to Github tells us nothing about solving those problems and just gets in the way of those who are currently looking after them.

[eddieajau]

1) It doesn't adversely affect end user contributions

Right, as long as "it's different" doesn't get translated into "adversely". The long term view would be to mimic what we are doing with Issues. It's perfectly acceptable to use Github for Issue management, but there are conveniences we can add on top of that (hence the creation of JIssues). I see this as a similar problem to solve.

2) We can deal with the translating of the docs as easily as we can with the mediawiki

Is there a definitive guide I can read up on in this regard?

Also my final thing is a new feature gets merged in but the docs will show for that new feature regardless of whether it's actually in the latest version of the component or not?

That's a good point. I think we'd look at putting all new changes into staging and manually merge to master. We will need to think about how we can make development builds though.

because I assume we're using the github wiki

No, docs are committed to the repository. I'd only use the wiki for information about, for example, contributing, extension roadmaps, etc.

Good questions. I've listed them here: https://github.com/joomla-extensions/weblinks/wiki#problems-to-solve Hopefully I'm not the only one who wants to get their hands dirty ;)

[eddieajau]

@chrisdavenport

but it's rare for developers to be able to write decent user documentation

I don't buy that at all but the point is to expect contributors to at least make a reasonable attempt at documenting their work before merge. It's much easier to continuously polish what already exists. It seems appropriate to use Weblinks as a test bed for this. We've already proven we can train people to contribute docs and tests with their code (in the Framework). Everyone who has been ask to provide these with their pull requests has been positive and eager to learn.

Now, if you were to suggest building an "ideal" documentation platform which happens to use Github as a repository, similar to how JTracker adds or compensates for deficiencies in Github's issue tracking capabilities, then you have my attention.

That's exactly what I'm thinking. But as with JTracker, you need the issues in Github first. Let's face it, Weblinks is not well used so there is no harm in upsetting the apple cart for this one extension. Let's keep the status quo for Banners et al in 3.5 until we are sure this can all work, but why not use Weblinks to make a mess in the hope that we make it better for tomorrow.

There are important challenges to be faced in working out how to integrate documentation for decoupled extensions. Moving the help screens to Github tells us nothing about solving those problems and just gets in the way of those who are currently looking after them.

I completely disagree about Github telling us nothing. It allows you to control when the documentation is added (or more to the point, it allows you to reject undocumented changes). It also gives you a level of curations over the documentation that isn't as easy on a free-for-all wiki. It would not prevent all mistakes from happening but it at least provides a way to catch some of them. Chris, despite the fact that the documenters work hard, the material is not finished on time for releases. We need to fix this.

Yes, I get some people will have to learn some new tricks. The problem is not their ability to learn them, it's the attitude towards wanting to that is the problem. What's the worst that can happen? People fall in love with Markdown and we get that supported in Joomla articles natively. Bring it on please!

[chrisdavenport]

"the point is to expect contributors to at least make a reasonable attempt at documenting their work before merge."

We can enforce that regardless of where the documentation is hosted. Indeed it is part of the new dev strategy.

"That's exactly what I'm thinking."

Well why didn't you say that? :p

"But as with JTracker, you need the issues in Github first."

If you mean that you need to move the documentation before you can build the tools that will manage it, then I disagree. I think the tools need to be in place first. Sounds like a chicken and egg situation, but if you just need documentation to test the tools then it's pretty easy to copy what is currently there without disrupting the documentation effort. Switch over when everything is in place and working, not before.

"I completely disagree about Github telling us nothing. It allows you to control when the documentation is added (or more to the point, it allows you to reject undocumented changes)."

We have control anyway. It's up to us to decide if and when code is merged and we can make that conditional on acceptable documentation being available regardless of where that documentation resides. The documentation requirement is already written into the new dev strategy; it's up to the maintainers to enforce it.

"Chris, despite the fact that the documenters work hard, the material is not finished on time for releases. We need to fix this."

Agreed, and that is why the documentation requirement has been written into the new dev strategy. But there's nothing in the strategy that says it has to be included with the code and committed in a PR (although that might be appropriate in some cases, such as Framework developer documentation).

"It also gives you a level of curations over the documentation that isn't as easy on a free-for-all wiki."

Pre-acceptance curation would certainly be useful sometimes, I'll grant you that. But the "free-for-all" is not as bad as it sounds. It is very rare for us to ever need to revert an edit. And it's not like someone writing a poorly worded sentence is going to break anyones website.

"What's the worst that can happen? People fall in love with Markdown and we get that supported in Joomla articles natively."

I wouldn't expect anyone to fall in love with any markup language, be it Markdown, MediaWiki, DocBook, DITA, XML, HTML or whatever. I would much prefer that they don't have to learn anything in order to write documentation. My ideal would be a WYSIWYG editor that guides the user in creating a structured document (or document fragments) without having to switch into "markup mode". Markup languages are what the system will use to save the data in and will allow the documentation to be handled by automatic processes for a variety of purposes. But they should not be for human consumption.

If you are serious about wanting to build an "ideal" documentation platform on top of Github (or wherever for that matter), then you have my support. But I think it is a much, much bigger project than merely decoupling weblinks and is very unlikely to be completed in time for the 3.4 release.

[eddieajau]

Ok, so what I'm hearing is new and innovative is off the menu for the foreseeable future but that does not mean we don't have some problems to solve, and at least we finally agree that documentation is part of a contribution. Therefore, can you give me some guidance on how to answer the following questions:

1. What instructions do I need to add to contributors regarding documentation for changes and new features?
2. What instructions do I need to prepare for repo maintainers to check the documentation is being fulfilled?
3. How are you going to handle staging of changes that are not in the current version. For example, if everything was on Github, we can stage all the changes in a branch and move everything to master when we cut a new build. How will you text and screenshots changes before the version they pertain to is released?

Thanks in advance for your direction on these matters.