Re: [PATCH] org-faq.org: Inline comments

[Bastien Guerry]

Ihor Radchenko  writes:

> Max Nikulin  writes:
>
>>> The proposed FAQ entry is overwhelming. It would work fine as a blog,
>>
>> A blog with a couple of posts a year has a little sense. Moreover it is 
>> closer to a wiki article because it is supposed to be updated. That is 
>> why I asked for an alternative location on Worg for bonus or extra 
>> material for the manual.
>
> I have no idea about alternative location.
> Maybe someone more familiar with WORG. Bastien?

FWIW, for such cases, I think a dedicated Worg page would make sense.

Also, yes, Worg css needs a lotta love.

-- 
 Bastien

Org FAQ design (Re: [PATCH] org-faq.org: Inline comments)

[Max Nikulin]

On 01/07/2023 22:24, Ihor Radchenko wrote:

Max Nikulin writes:


FAQ is probably fine. We may add a CSS there that will fold the
answers by default.


When all entries are opened, it is possible to use search in browser. I
am against the idea of hiding answers. However the table of contents,
that is rather long and revealed on hover only, makes it harder to
search in the TOC at first.


I am now watching
https://fosdem.org/2023/schedule/event/a11y_eaa_bfsg_wcag_wai_aria_wtf/


I have skimmed through the presentation.


They suggest a combination of  to keep hidden text
searchable. See 
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary


Unsupported by Firefox:

https://bugzilla.mozilla.org/show_bug.cgi?id=1724299
Implement auto-expanding 

I am unsure if it is possible to implement auto-expanding on link to 
specific question for Firefox.


However  is better than accordions in most cases.

I would consider to put TOC into 

P.S. Have you noticed that MDN pages have "skip to content" link hidden 
by default, but revealed on using keyboard (TAB).

Re: [PATCH] org-faq.org: Inline comments

[Ihor Radchenko]

Max Nikulin  writes:

>> FAQ is probably fine. We may add a CSS there that will fold the
>> answers by default.
>
> When all entries are opened, it is possible to use search in browser. I 
> am against the idea of hiding answers. However the table of contents, 
> that is rather long and revealed on hover only, makes it harder to 
> search in the TOC at first.

I am now watching
https://fosdem.org/2023/schedule/event/a11y_eaa_bfsg_wcag_wai_aria_wtf/

They suggest a combination of  to keep hidden text
searchable. See 
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] org-faq.org: Inline comments

[Ihor Radchenko]

Max Nikulin  writes:

>> The proposed FAQ entry is overwhelming. It would work fine as a blog,
>
> A blog with a couple of posts a year has a little sense. Moreover it is 
> closer to a wiki article because it is supposed to be updated. That is 
> why I asked for an alternative location on Worg for bonus or extra 
> material for the manual.

I have no idea about alternative location.
Maybe someone more familiar with WORG. Bastien?

>> FAQ is probably fine. We may add a CSS there that will fold the
>> answers by default.
>
> When all entries are opened, it is possible to use search in browser. I 
> am against the idea of hiding answers. However the table of contents, 
> that is rather long and revealed on hover only, makes it harder to 
> search in the TOC at first.

Maybe we can add a proper TOC at the top? Or convert the on-hover TOC
into proper one. TOC on top + detailed answers is how many FAQ pages are
designed.

> I have tried a random query "org-mode renumber footnotes" that is quite 
> close to an entry from the document. Nether Google nor Bing offered FAQ 
> on first 2 pages of search results. So FAQ is not friendly to search 
> engines for some reasons. I am unsure if the rank may be improved by 
> e.g. microdata schema.org attributes.

I wish we had somebody who is familiar with these things. I personally
have no idea what can be wrong and where to start to solve this problem.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] org-faq.org: Inline comments

[Max Nikulin]

On 29/06/2023 17:47, Ihor Radchenko wrote:

Max Nikulin writes:


I think, it is time to add a FAQ entry, see the attachment.


The proposed FAQ entry is overwhelming. It would work fine as a blog,


A blog with a couple of posts a year has a little sense. Moreover it is 
closer to a wiki article because it is supposed to be updated. That is 
why I asked for an alternative location on Worg for bonus or extra 
material for the manual.



To my taste FAQ is rather long already. If you have an idea of another
place on Worg where such tricks may be added then, please, share it.


FAQ is probably fine. We may add a CSS there that will fold the
answers by default.


When all entries are opened, it is possible to use search in browser. I 
am against the idea of hiding answers. However the table of contents, 
that is rather long and revealed on hover only, makes it harder to 
search in the TOC at first.


I have tried a random query "org-mode renumber footnotes" that is quite 
close to an entry from the document. Nether Google nor Bing offered FAQ 
on first 2 pages of search results. So FAQ is not friendly to search 
engines for some reasons. I am unsure if the rank may be improved by 
e.g. microdata schema.org attributes.

Re: [PATCH] org-faq.org: Inline comments

[Ihor Radchenko]

Max Nikulin  writes:

>>> Could it be possible to make inline comments (# something like this) ?
> ...
>> Previous discussion:
> ...
>
> I think, it is time to add a FAQ entry, see the attachment.

The proposed FAQ entry is overwhelming. It would work fine as a blog,
but not as a quick answer to a question. I recommend leaving only the
@@comment:...@@ part - it is what we use ourselves in WORG sources.

> To my taste FAQ is rather long already. If you have an idea of another 
> place on Worg where such tricks may be added then, please, share it.

FAQ is probably fine. We may add a CSS there that will fold the
answers by default.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at