Hello,
I'd like to propose and discuss with you an idea to create a repository that would contain, let's say, partials which are likely to be reused in Fedora's docs. Today, I think of Feedback.adoc or Legal_Notice.adoc, for example. But it could be also "about_fedora", "about_silverblue", descriptions of Fedora's flavors,...
The thing is I am not sure how strong such a use case it is. Will 3-4 document components (partials) which will be reused in up to ten documents just suffice to make a discrete place (repository? module?) for them? Where is the threshold? Could it be less or rather more?
I hope I didn't mistake myself and partials can be "xrefed" outside a module or even a repository.
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
I don't count myself among you, the docs writers. I have been translating Fedora for few years. I've also been following your mail list since I first noticed proposals to leave Publican tool chain. And this idea has come to my mind very recently, when I try to follow in my modest capacity the effort to build the tooling around Antora.
Please feel free to react for or against.
Josef Hruska fas: peartown
Hi,
that's a pretty good idea. Not sure about "about <product>", those aren't being reused at all I think (we *could* do that with a bunch of ifdefs, but for the love of everything that's holy let's not...), but the legal notice or the feedback page would definitely benefit from an arrangement like that.
I'll get on it let's say next week unless someone really objects to the idea.
Petr
On 3/23/19 6:01 PM, Josef Hruška wrote:
Hello,
I'd like to propose and discuss with you an idea to create a repository that would contain, let's say, partials which are likely to be reused in Fedora's docs. Today, I think of Feedback.adoc or Legal_Notice.adoc, for example. But it could be also "about_fedora", "about_silverblue", descriptions of Fedora's flavors,...
The thing is I am not sure how strong such a use case it is. Will 3-4 document components (partials) which will be reused in up to ten documents just suffice to make a discrete place (repository? module?) for them? Where is the threshold? Could it be less or rather more?
I hope I didn't mistake myself and partials can be "xrefed" outside a module or even a repository.
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
I don't count myself among you, the docs writers. I have been translating Fedora for few years. I've also been following your mail list since I first noticed proposals to leave Publican tool chain. And this idea has come to my mind very recently, when I try to follow in my modest capacity the effort to build the tooling around Antora.
Please feel free to react for or against.
Josef Hruska fas: peartown
docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
Hi Josef The ideas of partials allows one to "boilerplate a document", You just need to merge the sections you require and run it through asciidoc. Your second task is to review the technical names in each boilerplate and choose the one that matches a standard. It will necessitate creating a standard dictionary of some type. Even with the few wrinkles (dictionary, common terms, etc.) it is a good idea.
Regards Leslie Leslie Satenstein Montréal Québec, Canada
On Monday, March 25, 2019, 12:46:58 p.m. EDT, Petr Bokoc pbokoc@redhat.com wrote:
Hi,
that's a pretty good idea. Not sure about "about <product>", those aren't being reused at all I think (we *could* do that with a bunch of ifdefs, but for the love of everything that's holy let's not...), but the legal notice or the feedback page would definitely benefit from an arrangement like that.
I'll get on it let's say next week unless someone really objects to the idea.
Petr
On 3/23/19 6:01 PM, Josef Hruška wrote:
Hello, I'd like to propose and discuss with you an idea to create a repository that would contain, let's say, partials which are likely to be reused in Fedora's docs. Today, I think of Feedback.adoc or Legal_Notice.adoc, for example. But it could be also "about_fedora", "about_silverblue", descriptions of Fedora's flavors,... The thing is I am not sure how strong such a use case it is. Will 3-4 document components (partials) which will be reused in up to ten documents just suffice to make a discrete place (repository? module?) for them? Where is the threshold? Could it be less or rather more? I hope I didn't mistake myself and partials can be "xrefed" outside a module or even a repository. If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources). I don't count myself among you, the docs writers. I have been translating Fedora for few years. I've also been following your mail list since I first noticed proposals to leave Publican tool chain. And this idea has come to my mind very recently, when I try to follow in my modest capacity the effort to build the tooling around Antora. Please feel free to react for or against. Josef Hruska fas: peartown
_______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
Petr Bokoc píše v Po 25. 03. 2019 v 17:46 +0100:
Hi, that's a pretty good idea. Not sure about "about <product>", those aren't being reused at all I think (we *could* do that with a bunch of ifdefs, but for the love of everything that's holy let's not...), but the legal notice or the feedback page would definitely benefit from an arrangement like that.
Hi Petr, Yes, both, legal notice and feedback, are clear. I was not sure about the "about" things either. Maybe there will come other partials in the future, but it will probably be a result of a slower evolution.
I keep saying that I am not sure how strong the use case is. ;)
I had also one question in mind, but I didn't want to go to much detail in the introductory post. I don't have even idea where this "docs common" partials should have a home - should it be their own repository? If they should contain only two pages/files for the near future, I was thinking of making them part of the https://pagure.io/fedora-docs/template or maybe https://pagure.io/fedora-docs/release-docs-home.
Anyway, thank you for answering my post and your will to take an action.
Josef
I'll get on it let's say next week unless someone really objects to the idea. Petr On 3/23/19 6:01 PM, Josef Hruška wrote:
Hello,
I'd like to propose and discuss with you an idea to create a repository that would contain, let's say, partials which are likely to be reused in Fedora's docs. Today, I think of Feedback.adoc or Legal_Notice.adoc, for example. But it could be also "about_fedora", "about_silverblue", descriptions of Fedora's flavors,...
The thing is I am not sure how strong such a use case it is. Will 3-4 document components (partials) which will be reused in up to ten documents just suffice to make a discrete place (repository? module?) for them? Where is the threshold? Could it be less or rather more?
I hope I didn't mistake myself and partials can be "xrefed" outside a module or even a repository.
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
I don't count myself among you, the docs writers. I have been translating Fedora for few years. I've also been following your mail list since I first noticed proposals to leave Publican tool chain. And this idea has come to my mind very recently, when I try to follow in my modest capacity the effort to build the tooling around Antora.
Please feel free to react for or against.
Josef Hruska fas: peartown
docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
Le 23/03/2019 à 18:01, Josef Hruška a écrit :
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
Hello Joseph,
I'm only answering on the localization topic. It doesn't change much to have the same content in multiple places. We usually have the translation memory to take care of this kind of thing.
It definitely makes it easier for consistency (even in English), and saves us a little bit of time.
Would it be possible to have a language agnostic xref? So translators won't have to change the link.
Jean-Baptiste píše v Út 26. 03. 2019 v 07:57 +0100:
Le 23/03/2019 à 18:01, Josef Hruška a écrit :
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
Hello Joseph,
I'm only answering on the localization topic. It doesn't change much to have the same content in multiple places. We usually have the translation memory to take care of this kind of thing.
It definitely makes it easier for consistency (even in English), and saves us a little bit of time.
Hi Jean-Baptiste, Thank you very much for answering my post, too.
Yes, it isn't a strong use case for translation/localization, because (and that was exactly my thought from beginning) of the translation memory. However, I can remember when I was translating websites (I know they are not part of docs activities) of Fedora's spins/labs, pre- release etc., where there is the same text about support resources (on irc, mail, documentation) on each of them. The translation was, simply, time consuming, though I used available TM.
So the localization aspect, to have it on one place, was also clearly behind my motivation for the proposal.how to get help
Josef
Would it be possible to have a language agnostic xref? So translators won't have to change the link.
Hmmm, I look forward to an answer of (probably) Adam Samalik, too.
-- Jean-Baptiste Holcroft _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
On Wed, Mar 27, 2019 at 6:39 PM hrusjos@gmail.com wrote:
Jean-Baptiste píše v Út 26. 03. 2019 v 07:57 +0100:
Le 23/03/2019 à 18:01, Josef Hruška a écrit :
If the repository existed, it would IMO certainly facilitate also translations, for example (there could be, I assume, just one its translated sources).
Hello Joseph,
I'm only answering on the localization topic. It doesn't change much to have the same content in multiple places. We usually have the translation memory to take care of this kind of thing.
It definitely makes it easier for consistency (even in English), and saves us a little bit of time.
Hi Jean-Baptiste, Thank you very much for answering my post, too.
Yes, it isn't a strong use case for translation/localization, because (and that was exactly my thought from beginning) of the translation memory. However, I can remember when I was translating websites (I know they are not part of docs activities) of Fedora's spins/labs, pre- release etc., where there is the same text about support resources (on irc, mail, documentation) on each of them. The translation was, simply, time consuming, though I used available TM.
So the localization aspect, to have it on one place, was also clearly behind my motivation for the proposal.how to get help
Josef
Would it be possible to have a language agnostic xref? So translators won't have to change the link.
xrefs are language-agnostic, yes.
Hmmm, I look forward to an answer of (probably) Adam Samalik, too.
-- Jean-Baptiste Holcroft _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives:
https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
-
Adam Samalik -
hrusjos＠gmail.com -
Jean-Baptiste -
Josef Hruška
-
Leslie S Satenstein -
Petr Bokoc