J4 Help screens - Omit page name heading in proxy Topic is solved

Joomla! Documentation Workgroup

Moderator: Documentation

Locked
User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

J4 Help screens - Omit page name heading in proxy

Post by ceford » Thu Jun 25, 2020 5:02 am

The Administrator Help screens are reasonably well organised. I have been working from this list:

https://docs.joomla.org/Help4.x:Help_screens

However, the page name as displayed as H1 in the Help screen is often long and ugly and not so obviously connected to the screen it is called from. And they don't translate. For example, for the screen Articles -> Fields the pages heading is Articles: Fields but the help screen main heading is Help4.x:Components Fields Fields. And the version from Joomla 3 in German looks like this:
components-fields-fields.png
So I am thinking it would be better to have the Help Screen title heading actually in the help screen content and omit the page name in the proxy. I know this can be done because I have my own proxy which does this. Whether it is set as H1 or H2 is another matter.
You do not have the required permissions to view the files attached to this post.

User avatar
MartijnM
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 107
Joined: Thu Jul 26, 2007 2:46 pm
Location: Utrecht Netherlands
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by MartijnM » Thu Jun 25, 2020 8:36 am

I marked Components Fields Fields for transalation. Later today I will mark more of the helpscreens.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Thu Jun 25, 2020 11:07 am

By way of further illustration I added a h2 heading to Site Control Panel:

https://docs.joomla.org/Help4.x:Site_Control_Panel

It is not called directly as an Administrator Help screen but is linked from other pages. The disadvantage is that it appears as item 1 in the ToC. If it is made a h1 then everything else would be a sub-item and that is not right either. This is the appearance it might have as a Help screen:
site-control-panel.png
But only if the page Title is suppressed.
You do not have the required permissions to view the files attached to this post.

deleted user

Re: J4 Help screens - Omit page name heading in proxy

Post by deleted user » Thu Jun 25, 2020 7:18 pm

I would not suggest this.

Keep in mind, the rendered page in the help screen popout/iframe also includes rewritten links for everything in the docs wiki, meaning the entire wiki is browsed in that layout if you start following links (i.e. https://help.joomla.org/proxy?keyref=He ... _Dashboard has links to the non-help screen based guides on the privacy system). So either more complex processing would be necessary to only strip page titles out of the help screens, all page titles would have to be stripped out of the rendered page, or the status quo of all titles displayed is left in place. Unless you intend on changing the entirety of the docs wiki to deal with page titles in a usable way, I'd personally leave it alone as I think it'd be better to have the page titles than to start off with the content in a confusing manner.

https://github.com/joomla/help.joomla.org is where the code lives. As with most things in Joomla, it is open source and can be iterated on by any contributor.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Thu Jun 25, 2020 9:19 pm

I came across Help screens in English and French that have translated titles. Example:

https://docs.joomla.org/Help39:Site_Control_Panel
Site Control Panel

https://docs.joomla.org/Help39:Site_Control_Panel/fr
Panneau d'administration

So what I said previously was incorrect. It is possible to translate the title. I have not come across the method to do it but it would be nice to do it for the English base version so that the title is independent of the file name, allowing the Help page to have the same (or similar) title text as the screen it is called from.

What about the Help4.x vs Help40 or Help4x problem? I looked at the proxy code - a tad too complicated for me to patch.

deleted user

Re: J4 Help screens - Omit page name heading in proxy

Post by deleted user » Thu Jun 25, 2020 10:49 pm

Sandra or Tom don't frequent the forums (I really don't either) so you're probably better pinging them directly. If the change on wiki namespaces is permanent then assuming I can work out my regex skills it's a pretty quick change. If they're going to go back to the way things historically were then it isn't really worth the effort to make a code change.

Apparently there is functionality in MediaWiki to set a custom display title for pages. I have no idea how it's integrated into the translation flow, the one extension I found in their documentation doesn't seem to be used anywhere in that help screen's source content. Again, something to ping Tom and Sandra about, all I can really do is help with the rendered content through the proxy server application.

sozzled
I've been banned!
Posts: 13639
Joined: Sun Jul 05, 2009 3:30 am
Location: Canberra, Australia

Re: J4 Help screens - Omit page name heading in proxy

Post by sozzled » Thu Jun 25, 2020 11:36 pm

I always appreciate @mbabker's thoughts on just about everything but, of special significance, his observation about the absence of key personnel in the J! project from the forum.

While I don't understand the technical implications of @ceford's questions, I commend him for his dedication and perseverance in seeking to improve the documentation for J! 4. I hope that his enthusiasm for documentation continues. :) Well done!

I'm disappointed that the "sticky topic" relating to documentation in general remains as it is—a signpost in "tumbleweed city" that was written thirteen years ago—and probably is outdated. Who knows?

There are many areas of interest to J! users where the forum is the first (and often the last) point of contact. Without wishing to characterise the forum or the J! project in any bad light, it's fairly evident that some people who are responsible for the promotion of the J! brand (no names, no packdrill) consider the forum as a relic of a bygone era or something that is not worth paying any attention to. It's a pity that we forum users are [perhaps] regarded as "bottom feeders" in the food chain. C'est la vie.

Nonetheless, we plow on and were it not for the help that sympathetic volunteers like @mbabker we'd be worse off. So, as a general thought-in-passing, one needs to use one's own research ability and "ping" (if one knows how to do that) those who may have the answers to our questions rather than living in hope that our questions on the forum will be addressed.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Fri Jun 26, 2020 8:14 am

Some more discoveries (for me):

On the
Panneau d'administration
page the Actions list has a Translate item and the first thing on the translation form is the Page Title. That feature is not present for the base or English versions. So the only way to change the page title in English appears to be to move it. I am not going to do that just to change the English title of Help Screens. The Mediawiki documentation is not very helpful - it implies that changes to the page title are limited to changes of case, such as IPod to iPod.

I have tried contacting the Documentation team using the Contact tab on the Documentation Team page and by using Talk pages. I have found that unsatisfactory - no copy for me of my communication and no direct answers. Rather like praying, things happen - but is it in answer to my prayers or just nature taking its course. The Documentation wiki has been cleaned up recently, with a bunch of outdated closed, fixed to top announcements being removed. That is a good sign.

What does
Ping
mean in this context? I think we really need to find out from the Documentation team whether the prefix Help4.x can be changed to Help4x.

deleted user

Re: J4 Help screens - Omit page name heading in proxy

Post by deleted user » Fri Jun 26, 2020 12:25 pm

sozzled wrote:
Thu Jun 25, 2020 11:36 pm
I always appreciate @mbabker's thoughts on just about everything but, of special significance, his observation about the absence of key personnel in the J! project from the forum.
There’s no mandate that leadership spends 2 hours per week on the forums. Apparently there are enough issues just getting them to read the chat platform messages and emails (seriously, it should never have to be an official motion of the corporation that there is a requirement for frequency of checking email, yet that has happened).

Years ago, there were three communication platforms for Joomla: JoomlaCode (being the project’s source control and issue management solution), IRC (because people like real time chat), and the forums. The times have changed, the project uses a closed off invite only platform for chat, JoomlaCode is effectively replaced by GitHub, mailing lists that were once frequently used are now collecting cobwebs, and parts of these forums are all but abandoned. That last point is most obvious when it comes to the management of the joomla.org infrastructure, which has shifted primarily to GitHub (which I still think is a good thing, it puts issue reports and discussions on the same platform that is used for Joomla development and those reports live more closely with the code (in a growing number of cases) and are more easily referenced as changes occur and saved for historical reference).

All that is to say that I don’t think anyone needs to shun any leadership team members if they choose not to use these forums. Truth is the forums serve their primary purpose quite well (IMO that primary purpose is to provide a forum, no pun intended, where users can seek guidance and support from others in the community), and leadership team members should be under no obligation to provide free end user support (since they’re already volunteering their time in other ways). And while categories exist for a number of project teams, aside from the JED’s category, there is very little activity in those areas anymore and I think that’s just a reflection of times changing and people using different mediums to handle their business. Right now it seems like the best medium for most project business is on Glip if you’re lucky enough to get into the invite only platform.

User avatar
MartijnM
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 107
Joined: Thu Jul 26, 2007 2:46 pm
Location: Utrecht Netherlands
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by MartijnM » Fri Jun 26, 2020 12:28 pm

I posted something on Glip in the documentation group about this

sozzled
I've been banned!
Posts: 13639
Joined: Sun Jul 05, 2009 3:30 am
Location: Canberra, Australia

Re: J4 Help screens - Omit page name heading in proxy

Post by sozzled » Fri Jun 26, 2020 7:23 pm

ceford wrote:
Thu Jun 25, 2020 9:19 pm
What about the Help4.x vs Help40 or Help4x problem? I looked at the proxy code - a tad too complicated for me to patch.
As I wrote earlier, I'm not sure I understand the issue.

When I go to the backend of a J! 3.8[.13] website and click the help menu item, I see
j3xHelp.jpg
You see the same thing in the backend of a J!3.9[.19] website, too.

With J! 4.[0.0.beta2-dev] it's a little different
j4xHelp.jpg
Is this what we're discussing? If I've veered off-topic then I apologise. I'm merely trying to get a handle on the discussion.

The essential point of using The Joomla Forum™, particularly the forum category entitled
Joomla! Official Sites & Infrastructure docs.joomla.org » Feedback/Information is that, as @mbabker and @MartijnM and I have alluded to, this forum is not where detailed discussions about documentation are done. As @mbabker mentioned, many activities associated with the J! project are managed elsewhere these days both in public (e.g. GitHub) and in private (e.g. invitation-only chat rooms) and sometimes you have to be "lucky" to get invitations to these things.

Also, as I wrote earlier, I don't wish the expression of my views here to be characterised in any bad light. Things are what they are. I agree with @mbabker that no one needs to shun team members (or their leaders) who choose to use one or another communication method. By the same token, ordinary people who use these public forum should not feel isolated or shunned, either.

Documentation is a tough job and probably involves more time than the time spent writing the source code. It's an unrewarding task for which people are rarely given recognition. I know (from my personal experience, having written 500+ [mediaWiki] help articles for a project I was involved with for five years or more) how little appreciation is given to people who spend their hours learning the vagaries of <insert documentation software name here> to explain how a product works.

I'm only saying that I'm disappointed by the inadequate public commitment to forum users seeking information. This forum, run by volunteers, is where we have to help ourselves and stumble as we learn along the way. I wish I could help you, @ceford.
You do not have the required permissions to view the files attached to this post.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Sat Jun 27, 2020 6:40 am

sozzled wrote:
Fri Jun 26, 2020 7:23 pm
When I go to the backend of a J! 3.8[.13] website and click the help menu item, I see j3xHelp.jpg
Actually, in J3 the Help page you illustrated is the first item in the Help menu. In J4 the Help menu leads to a dashboard and it is not obvious which link leads to the Start Here page. Which is my excuse for not remembering ever having seen it. Thanks for that. Arghhh! However...

The pages there are the same pages I have been referring to but appearing in a modal box in response to selection of the Help toolbar button. Here is an example:
help4x-problem.png
The points I have been making are that Help4.x is not relevant and would be omitted by the proxy server if it were Help40 or Help4x. And that often the Help page title is not the same as in the Title bar of the page it purports to support (unless translated into a language other than English).

Another usability snag just discovered. If you scroll down the Start Here page and click Smart Search nothing happens. Actually the page has changed but the change is out of site. So we need a line of Javscript to scroll to top - I will report that as a bug.
You do not have the required permissions to view the files attached to this post.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Wed Jul 01, 2020 3:42 pm

This issue has been resolved. The prefix remains Help4.x but the proxy has been adjusted to take this into account.

User avatar
ceford
Joomla! Hero
Joomla! Hero
Posts: 2615
Joined: Mon Feb 24, 2014 10:38 pm
Location: Edinburgh, Scotland
Contact:

Re: J4 Help screens - Omit page name heading in proxy

Post by ceford » Thu Oct 01, 2020 4:56 pm

It has already been reported - and the solution is to put the index in a scolling div the same height as the page. It is just waiting for someone to take it up.


Locked

Return to “docs.joomla.org - Feedback/Information”