Scope

This ticket #2942745 is about discussing the audience' needs for clickable anchor icons, inclusively for those documentation pages and their sub-pages at:

This ticket #2942745 is not about anything else than the above scope of efforts. In other words, this ticket is:

  • Not about updating this documentation guideline. If you need to discuss this, you're welcome to join the efforts in another ticket at #2943370 :)
  • Not about other documentation pages than the other pages listed above

Francewhoa's Reply to hansfn

Hi hansfn :) Thank you for all your contribution to Drupal. And thanks for your proposal about removing all the clickable anchor icons
Which are into those documentation pages and their sub-pages at:

Maybe you did not know that those clickable anchor icons were requested and are needed by non-developers & newcomers

In the future, before your remove those clickable anchor icons, I would like to invite you to a discussion on this ticket. I understand that your proposal is to remove them because they are not usual invisible anchors.

I'm assuming that you did not know about the other users' needs. I receive your email, you were wondering about the purpose of those clickable anchor icons. I hope the following User Stories and its Assumptions answer your question.

User Story

As non-developers & newcomers to "Updating Drupal 7, 8" documentation pages we need clickable anchors in the documentation pages, so that:

  • we can easily and quickly copy a link/url to a specific documentation page section
  • we have a visual reminder about available clickable anchor icons

Assumptions

  • Assumes that by "non-developers" we means the user does not have the skills to open the page code to locate and copy the anchor and manually build a URL with an anchor.
  • Assumes that by "newcomers" we means folks who are new to Drupal documentation and presently have junior skills

There was a past discussion about the above User Story and its Assumptions. Back then the consensus was to, in addition to the usual invisible anchors tags, to simply add clickable anchor icons

As maintainer of those documentation pages, I'm in progress of restoring those removed clickable anchors. I'm assuming you removed those in good faith and did not know about the User Story and Assumptions above.

I set this ticket to "work as designed". Feel really free to re-open it if you have another proposal that you meet the needs of all users about the new information with that User Story and its Assumption above :)

Cheers,

Francewhoa

Comments

Francewhoa created an issue. See original summary.

francewhoa’s picture

Issue summary: View changes
hansfn’s picture

There was a past discussion about the above User Story and its Assumptions. Back then the consensus was to, in addition to the usual invisible anchors tags, to simply add clickable anchor icons

A simple reference to that discussion, immediately, would have save me a lot of (editing) time - and frustration since you seemed to just ignore my comments and didn't reply to the PMs I sent you.

I think the visible anchor indicators look ugly has a hell, but if there is a consensus about adding them we shouldn't waste any more time on this issue.

hansfn’s picture

Just a couple of remarks:

Adding such visible anchors manually is a not good. It should be inserted automatically using Javascript for all h2 (and h3) elements that have id attributes (and hence is an anchor).

I also recommend that we use

<h2 id="title...">Title...

instead of

<h2><a id="title..." name="title..."></a>Title ...

when we define the anchor.

hansfn’s picture

Status: Closed (works as designed) » Active

On second thought, I think this issue should be open until there is a link to the past discussion. And, much more importantly, this should be documented in the content guidelines.

francewhoa’s picture

Dear hansfn :) Thank you for your reply #3 above

I think the visible anchor indicators look ugly has a hell

Same here. Back then years ago we tried at least 20 different draft proposals. The consensus was that this was the less-ugly option, LOL ;) Actually the favorite option was a CSS hidden clickable anchor. In other words, invisible by default, and visible on mouse over only. But such CSS is not yet supported in Drupal doc. We tried, but on save, those CSS are automatically filtered out by the text filter. Bummer :(


A simple reference to that discussion, immediately

This is your reminder that most contributors to Drupal are unpaid volunteers like you

No worry I will not try to interfere with you <3. How about you, are you going to try to interfere with other contributors? By "interfere" I mean telling others how, or when, or where to contribute.

Your proposals are really welcome :) But interference is not :( If you will go on the "interference" road I'll let you go there alone. Sorry.

With infinite Drupal love and without interference ♥


since you seemed to just ignore my comments and didn't reply to the PMs I sent you.

I'm assuming you're asking if I was ignoring your comment. No I was not. As you know I'm a volunteer. I would love to reply immediately but that's not realistic with my present workload. Speaking for myself I batch my replies. Delay can be anywhere between hours and months. My previous reply above was included in my last batch. Feel free to reply to your comments when it's convenient for you and use any format to your liking. To each their own.

By the way I replied twice to your private messages (PMs). Via direct email and via reference in Drupal.org. Then you replied to both of them. So I'm assuming your received my PMs. Maybe somehow an email glitch between you and me resulted in you not receiving my replies, or the mischievous spam folder, LOL (joke ;)


, but if there is a consensus about adding them we shouldn't waste any more time on this issue.

Sure let's move on to another contribution :) In the future, if you change find another resolution to the challenge about this User Story and its Assumptions above, you're always welcome to join the efforts with your proposal :)

I'm signing off for today. Enjoy the remaining of your day.

With infinite Drupal love ♥

francewhoa’s picture

Status: Active » Needs work

@hansfn :) I saw now your last two comments #4 and 5 above

Thanks for your recommendation :) As you know I'm signing off for today. I'll reply as soon as I'm free. Bye for now :)

hansfn’s picture

Interference? Didn't I invite you discuss the duplicate pages/content for the Drupal 7 update pages? I didn't just merge the pages and ruin your work. When it came to these visible anchor links I couldn't for the best of my knowledge understand the purpose of them and it was not documented in the content guidelines. (The guidelines recommend a TOC with links to the headers/anchors.) So I removed them with best intention. And I did it twice - still with good intentions. When you reverted my first edit, you wrote "Anchors are needed to facilitate navigation between pages." Since the stuff you added wasn't the anchors (but actual links so people could easily find the anchors) I didn't get what you were trying to do. At this point I sent you two PMs which resulted in this issue.

NB! The comments I was talking about was the comments in the editing history/discussion for each page. Looking back at the comments we are both trying to explain to each other what we are doing. I'm sorry that I accused you of ignoring these comments - we just talked past each other. And when I wrote "immediately", I also ment in these comments. I never expect people to reply immediately on email.

Anyway, it is important to me that this gets documented in the content guidelines if this is how we should do it. I thought the "correct" way was to add a TOC (which are links to the anchored headings) for long pages. Short pages, that doesn't need a TOC, also doesn't need anchors.

It might be better to create a new issue for updating the guidelines, but now I have to go too - to my non-Drupal related work.

drumm’s picture

Same here. Back then years ago we tried at least 20 different draft proposals. The consensus was that this was the less-ugly option, LOL ;) Actually the favorite option was a CSS hidden clickable anchor. In other words, invisible by default, and visible on mouse over only. But such CSS is not yet supported in Drupal doc. We tried, but on save, those CSS are automatically filtered out by the text filter. Bummer :(

Do you have a link to this discussion? Drupal.org has only supported emoji for about 8 months, #2463607: Drupal.org chokes on emojis

I haven't seen a literal ⚓️ emoji used like this anywhere else on the internet. The convention I know about is a #, which is on a few pages throughout Drupal.org, but not standardized.

hansfn’s picture

To benefit of other readers, I post links to pages where the different approaches have been used.

francewhoa’s picture

Issue summary: View changes
Issue tags: +clickable anchor icons

Hi hansfn :)

Anyway, it is important to me that this gets documented in the content guidelines if this is how we should do it.
It might be better to create a new issue for updating the guidelines, but now I have to go too - to my non-Drupal related work.

Thanks for your proposal. Today I created this ticket #2942745. You're welcome to add your proposal to it, about adding this to the guidelines.

As you know this ticket #12474060 is specifically about those pages and their sub-pages below. Not all documentation pages. I propose to keep in mind that each documentation book and its related pages have a unique audience. Which has unique needs. To each their own.

Scope of this ticket #2942745

My vote goes for keeping optional the clickable anchor icons. Depends on the context. On some pagex it might be needed, on other pages it might not be. Depends on the audience. I noticed that visible clickable anchor icons are more often needed for newcomers. Senior Drupal Devs often don't need such anchors. Any how if they do, and the anchors are not visible, they usually know how to find invisible anchors into the page code.


And when I wrote "immediately", I also ment in these comments. I never expect people to reply immediately on email.

Thanks for clarifying that you did not intended interference. As you know by "interfere" I meant telling others how, or when, or where to contribute. I was also implying not interfering in any type of communications. Including but not limited to Drupal.org comments or direct email. As you know I will not try to interfere with you ♥. I would welcome the same in return.

francewhoa’s picture

Issue summary: View changes

@Francewhoa :) Note to myself. I'm in progress of restoring this ticket original "Issue summary". I did a typo in my last comment. I added it to the wrong field. Which in turn overwrote my original "Issue summary". D'Oh.

francewhoa’s picture

Issue summary: View changes

@Francewhoa :) Note to myself. Done I restored my original "Issue summary". Added a "s" to "discussions".

francewhoa’s picture

Title: Clickable Anchors for Non-Developers & Newcomers » Clickable Anchors for Non-Developers & Newcomers Anchors. "Updating Drupal" Pages.
Issue summary: View changes

@Francewhoa :) Note to myself. To facilitate communications & clarify scope, I updated both title and summary.

francewhoa’s picture

Issue summary: View changes

@Francewhoa :) Note to myself. To facilitate cross-ticket communications, added invisible anchors.

francewhoa’s picture

Hi drumm :) Thanks for all your Drupal contributions. About your comment #9 above, my reply is in this other ticket at https://www.drupal.org/project/documentation/issues/2943370#comment-1247...
This other ticket #2943370 is about a proposal about adding to this documentation guideline a new section about optional the clickable anchor icons.

This ticket #2942745 is about discussing the newcomers and non-developer audience' needs for clickable anchor icons. Inclusively for some documentation pages and their sub-pages, which are listed under this "Scope" section above. Maybe my previous ticket summary was not clear about the scope.

hansfn’s picture

Yeah, the scope completely passed under my radar. The scope clearly needs to be extended to the install pages as well. I can easily see a problem limiting the scope.

Anyway, I'm not sure I like that some pages should look very different than other pages - the emoji anchors are very visible :-) I think I will continue the discussion in the other issue you created. Thx a lot for creating that issue.

If we agree in the other issue about such anchors being optional (and how to insert them), we have nothing more to discuss here - IMHO.

francewhoa’s picture

Status: Needs work » Fixed

Hi hansfn :)

If we agree in the other issue about such anchors being optional (and how to insert them), we have nothing more to discuss here - IMHO.

Agreed. With #2942745 we have a clear understanding of the needs of non-developers & newcomers for those pages listed above.

I'm closing this ticket #2942745. In the future, if the contributors reach a general consensus with #2943370, we could re-open this ticket #2942745.

francewhoa’s picture

Issue summary: View changes

@Francewhoa :) Note to myself. For easier navigation, added invisible anchors to #2942745.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

bertboerland’s picture

Noticed it and created an issue https://www.drupal.org/node/2953847/ that is closed now. My points are still valid. These anchors are not inline with the rest of the icons, redundant and lead to mystery navigation just showing we are a tech community that that give about normal people who dont know HTML. :-(

we *must* delete these icons!

(from the issue:
I recently saw that we use anchor icons for anchor links on documentation pages, for example see https://www.drupal.org/node/1494290/

This is not what we should do IMHO
* the anchor icon itself is not inline with the rest of the flat design of d.o creating a bad ux
* the anchor icon is a technical metafore that many editors might understand but none of the readers. Think about this, if you dont know HTML and you are reading a text with out of nowhere has anchor icons next to headings, what does that communicate?
* the most used way of doing this is just by linking the title itself

From the revisions (https://www.drupal.org/node/1494290/revisions) I see the icon has been removed and aded. Can we settle this towards no icon?
)

bertboerland’s picture

ships, cant reopen this issue. so will reopen mine, this is too important to let it go by.

hansfn’s picture