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.

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

Ping @chrisdavenport and @Hutchy68 😄

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.

Roberto, that's my preferred view as well.

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

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 ;)

Also for help screens don't forget about this joomla/joomla-cms#3351

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

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

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.

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.

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.

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

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 :)

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.

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.

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.

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.

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

I have some ideas.

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)?

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.

Can you link me to an example?

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.

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.

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

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.

@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.

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.

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.

I have the feeling more and more, whether concerning the docs or the discussion here #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.

@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).

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

@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".

Language is part of B/C

Documentation isn't. Wrong thread perhaps?

@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.

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.

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

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

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 GitHub#3 (comment)
.

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?

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.

@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.

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)

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.

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 ;)

@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!

"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.

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.

You know has really good user docs? WordPress. And I'm not talking about their wiki, I'm talking about the docs you find on component admin screens, the user docs.

I for one was under the impression that decoupling meant everything, including docs. If we can find a better process, including docs, I'd say go for it. I do think the current system of using a language string to locate a help file location is pretty baffling (why should we require usage of the language extension to locate a file again?) but it's the system we have now. No reason not to work on potentially improving that.

Sent from my iPhone

On Apr 12, 2014, at 4:49 PM, Andrew Eddie notifications@github.com wrote:

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:

What instructions do I need to add to contributors regarding documentation for changes and news features?
What instructions do I need to prepare for repo maintainers to check the documentation is being fulfilled?
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.

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

why should we require usage of the language extension to locate a file again?

I guess it allows for translated docs? And the translated doc doesn't even have to be hosted on the same server as the original one does. It can be anywhere. It's actually quite clever I think.
If I understand it correctly, that is.

I guess it allows for translated docs? And the translated doc doesn't even have to be hosted on the same server as the original one does. It can be anywhere.

Besides being hosted anywhere or in local files, it allows extension developers to provide help screens to their extension across multiple languages. So a French developer can provide help in English, Italian or whatever... Then if a admin is using the Italian admin interface, they see the help for the extension in their own language.

You know has really good user docs? WordPress.

Wordpress, Symphony, etc... Apples and oranges as far as docs IMO as I stated before, corporation support of paid staff vs. true volunteer(unpaid) FOSS project.

And I'm not talking about their wiki, I'm talking about the docs you find on component admin screens, the user docs.

These text pieces on a help slider?

I don't know if I would classify them as help screens. They are really little snippets of "extended info" with links leading out of admin panel back to WP's wiki for more info. Some are no more than a sentence, others are longer explanations(which I provided screenshots) of fields and forms if WP doesn't have the italics what is this field help under the interface choices. I don't know for sure without downloading a WP package, but I would imagine these help snippets are part of the code's local files. Much like our tooltips on hover, which would add more work for the translation teams.

I for one was under the impression that decoupling meant everything, including docs.

I was under the impression we were trying to decouple the core components to see if it can be done while applying the same rules and methods current extension devs use for their Joomla! extensions on the JED. Hence, request(and its approval AFAIK) for core's own category on the JED. Now we are talking about a complete redo of the help system unless I am missing something?

Yes, it does allow for translated docs, however, in the case of loading a file from the filesystem, you have to put in a language key that contains the name of the file. Regardless of lang, the file name is always the same, just on a different folder. When dealing with separation of concerns in programming, it seems rather un-intuitive that the language extension is required for figuring out the file name. You should just be able to pass a file name and not involve the language code in the process except to figure out the active language of the site and use that (in code outside of lang itself) in order to load the appropriate file. It may seem like a small difference, but as I said when dealing with separation of concerns it's big. Think of it this way, when writing the unit tests for the language code, why in the world does it make sense to have to test the ability for language to locate a file.

I realize these are lofty goals, and most likely things we can't fix without breaking BC, so it's something to consider for 4.0.

Tom, we already know that decoupling the code from core and keeping all other processes the same will work fine. That part has been proven out since 2012 when Michael did the J!Lite stuff. If that's the extent of the decoupling, that's fine, we can probably get more than just weblinks out of core then for 3.4, since there's a lot less work to do.

Sent from my iPhone

On Apr 13, 2014, at 2:03 AM, Thomas Hunziker notifications@github.com wrote:

why should we require usage of the language extension to locate a file again?

I guess it allows for translated docs? And the translated doc doesn't even have to be hosted on the same server as the original one does. It can be anywhere. It's actually quite clever I think.

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

@eddieajau. Now you're starting to ask the right questions! I'll try to write up some notes that will hopefully give some guidance.

@Bakual. That's correct. It even allows the URLs themselves to be fully localised so it isn't necessary to have anything exposed to the user in English. I don't know if even WP manages to achieve that level of localisation.

@dongilbert. The reason for using a language key containing the "file" name is to allow for complete localisation of URLs. It means I can have help screens with URLs in my own language without having to embed language codes if I choose. It means that third-party developers retain control over the URL structure of their help systems and we're not dictating that localised URLs must contain language codes.

I actually think that it's a good idea to decouple code and documentation (with the exception of things like docblocks obviously). Code never needs to be translated, whereas documentation always does. By all means make it an absolute requirement that English documentation is available as soon as the code is released (that's something I've wanted right from the start), but it would be unrealistic to expect all the translations to be available at the same time as well (though some might be). It's also good to retain the flexibility to modify the user documentation in the light of experience of how people are actually interacting with the software, without the need to push out a patch release.

Now you're starting to ask the right questions! I'll try to write up some notes that will hopefully give some guidance.

What choice does one have when faced with resistance to change. I don't agree with your stance but I have to respect that you have the authority. Whatever you want will be.

If that's the extent of the decoupling, that's fine, we can probably get more than just weblinks out of core then for 3.4, since there's a lot less work to do.

If code is the only change on the table, I think we make no changes at all in 3.x and just drop the non-essential extensions completely in 4.0.

I would not call realism and experience a "resistance to change".
Anyway, as the main reason for decoupling was originally to prevent reinstalling an uninstalled extension when updating Joomla, this can be done for code only, keeping docs and language files as are.

Anyway, as the main reason for decoupling was originally to prevent reinstalling an uninstalled extension when updating Joomla, this can be done for code only, keeping docs and language files as are.

Can you please work on the instructions and/or workflow that contributors and repository maintainers need to be aware of regarding language files. Better yet, just add those instructions to the contributing.md in a PR and I will merge it (and then I'll move onto something more interesting).

I guess PLT would be in charge of this. I am just a CMS maintainer (among other hats).

I guess PLT would be in charge of this. I am just a CMS maintainer (among other hats).

They are just going to ask you what you will approve of.

"What choice does one have when faced with resistance to change."

I'm all in favour of change if that change is an improvement, but I'll naturally resist change if it moves us backwards.

As it stands right now, Github is not a suitable platform for most of our documentation. Now, if Github can fix the deficiencies, or if you or anyone else can build the tools that can compensate for its shortcomings, then I'd be perfectly happy to move to Github. And I'd say the same to anyone suggesting that we move to Joomla too (which with the addition of content versioning and tags is starting to look like a contender). In the meantime we just have to make the best of what we have.

but I'll naturally resist change if it moves us backwards.

The problem is I feel you have decided this is all a backwards move without even giving it a fair hearing. I think you are being completely unreasonable not even trying to work with people are are genuinely trying to strive for real and tangible improvements.

Nothing could be further from the truth and I'm sorry that you feel that way . If you can show real and tangible improvements then of course you will have my support, but I'm just not seeing them at the moment. Perhaps you need to flesh out your proposal so we can see in more detail how you are proposing to address the issues.

So how about we frame this under the concept of a trial? I want to see if this system can work, but I don't want to invest hundreds of hours in tools to help the system work if the system itself doesn't work in a manual fashion.

Trial Goals

1. Change the document format from Mediawiki markup to Markdown markup

Pros:

• Easy to learn
• Easier than MW to remember the basic markups
• Far, far more widely supported in editors than MW, and also in other CMS (WordPress, etc).

Cons:

• New format to learn

2. Change the storage or documentation from MediaWiki to Github

Pros:

• Centralises the contribution of code and documentation
• Allows for documentation to be finished when new releases are built
• Allows for curation at contribution time rather than sometime after
• Allows for structured additions of tutorials
• Allows for an extension to focus on the documentation it needs rather than being buried in a wiki
• Allows for staging of changes in alpha's and beta's, etc.
• Allows for the extension to independently arrange the documentation in the way that makes sense for it

Cons:

• Some people find PR's difficult to navigate
• Organising documentation is placed on the contributor's shoulders rather than relying on the documentation fairies
• Will require resourcing (aka budget) for researching tools to help make editing files easier (but this is something the entire Open Source community would welcome so it's a noble endeavour).
• Some things in Github are still a bit quirky (for example, you can't refresh your fork via the UI - but let's strike up a dialog with Github command about that)

3. Experiment with a change of publishing from MediaWiki to Github pages

Pros

• GH Pages is a rich static site format well suited to non-dynamic data
• Automatically converts Markdown files into HTML with Github Flavoured Markdown. This is especially good for code snippets.
• The contributor does not have to worry about the gh-pages branch. They simply add docs to the /docs/ folder according to agreed rules of file placement.
• Building of the gh-pages branch can be fully automated in conjunction with build process for releasing files.
• The template can be configured to act responsively to suit a help screen modal or a browser screen.

Cons

• Requires a bit of work to set up the gh-pages branch
• Jekyll can be temperamental when trying to work out why the build failed.

That's a broad overview. There is as yet no evidence that it's a backward step until we actually try it so I'd prefer if people reserve judgement until we see it in operation. It may very well fail but I bet it's for reasons you don't expect. And if it does fail, we've lost nothing and can revert to the status quo at the final hour, though, I'd like to give this a live trial for 3.4.

Because Weblinks is not a popular extension, it seems fair to use it as a bit of a safe playground to either prove a new paradigm, which incidentally will make it much easy for 3PD's to follow. I'm not proposing changing the documentation systems for the core at all so there's no threat to all the work that's been put into existing systems (but realising those systems are not perfect - they just have the strategic advantage of being the status quo).

The bottom line is I equate decoupling with independence. I think that trying a completely centralised approach is worth the risk and doing it now on one package will allow us to gauge whether it can be successful for more off-core extensions. I would go so far as to say the current documentation system is going to fall in a flaming heap by the time we have a dozen active off-core extensions and some sort of new tool is going to be required to help us preserve our sanity anyway. So let's start trialling some different methods before the storm hits.

I could take issue with your list, but I have no objection to a trial.

I could take issue with your list

As long as it's based on objective criticism, I have no problem with that. In fact, I expect it.

but I have no objection to a trial.

Ok - that's all I was after. Thanks.

Closing issue. Status quo seems to be the path of least resistance.