19:31:13 <darknao> #startmeeting docs
19:31:13 <zodbot> Meeting started Wed Dec 14 19:31:13 2022 UTC.
19:31:13 <zodbot> This meeting is logged and archived in a public location.
19:31:13 <zodbot> The chair is darknao. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
19:31:13 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
19:31:13 <zodbot> The meeting name has been set to 'docs'
19:31:25 <darknao> #topic Roll call
19:31:28 <darknao> #chair pboy darknao pbokoc py0xc3[m]
19:31:28 <zodbot> Current chairs: darknao pbokoc pboy py0xc3[m]
19:31:31 <pboy> .hi
19:31:32 <zodbot> pboy: pboy 'Peter Boy' <pboy@uni-bremen.de>
19:31:55 <AlanBowman[m]> Hello
19:32:25 <hankuoffroad[m]> .hello hankuoffroad
19:32:26 <zodbot> hankuoffroad[m]: hankuoffroad 'None' <allegrovelo@gmail.com>
19:32:31 <AnthonyMcGlone[m> Hi
19:32:41 <hankuoffroad[m]> hi all
19:34:18 <darknao> Hi everyone!
19:34:26 <darknao> let's start
19:34:29 <darknao> #topic Agenda
19:34:36 <darknao> #link https://discussion.fedoraproject.org/t/docs-meeting-agenda-2022-12-14/44859
19:34:39 <darknao> #info Announcements
19:34:41 <darknao> #info Quick docs update
19:34:43 <darknao> #info Open Floor
19:34:44 <darknao> #topic Announcements
19:34:54 <darknao> #info Old Fedora docs (anything older than F26) have been retired.
19:34:57 <darknao> #info New version of Docs UI has been deployed. See the list of improvements here:
19:34:59 <darknao> #link https://discussion.fedoraproject.org/t/discussing-fedora-docs-website-improvement/36600/34
19:35:02 <darknao> #info AsciiDoc for Fedora documentation has been updated, check it out:
19:35:05 <darknao> #link https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/asciidoc-markup/
19:35:07 <darknao> #info Next milestone is F38 (2023-04-18)
19:35:10 <darknao> #info We use GitLab to track work: https://gitlab.com/groups/fedora/docs/-/boards
19:35:20 <darknao> anything else to mention?
19:36:32 <darknao> ok, moving on to the main topic then
19:36:45 <darknao> #topic Quick docs update
19:37:56 <pboy> Well, question is, where we are.
19:38:06 <pboy> #link https://pagure.io/fedora-docs/quick-docs/issues
19:38:43 <pboy> I think:
19:38:55 <pboy> #link https://pagure.io/fedora-docs/quick-docs/issue/525
19:39:37 <pboy> is the easiest. Does there anybody objects to remove that article? (I already did, but we can frevert)
19:40:05 <hankuoffroad[m]> I took one myself to rewrite Finding and installing Linux applications - link here https://pagure.io/fedora-docs/quick-docs/issue/521
19:40:43 <AnthonyMcGlone[m> I had one ticket merged. I'll took another and will continue with that.
19:41:02 <darknao> regarding the iptables one, I have no objection in removing it. Users should use firewalld instead.
19:41:07 <pboy> hankuoffroad[m]  yeah, that's the question about partials
19:42:10 <hankuoffroad[m]> pboy: Beyond me. Anyone?
19:42:15 <pboy> Hm, pagure is quite slow, actually
19:43:31 <pboy> hankuoffroad[m] My internal translator hangs. :-) wha do you mean?
19:44:44 <pboy> regarding #525 / iptables. I'll close it then.
19:45:38 <darknao> hankuoffroad[m]: regarding partials, you want to know how to edit them?
19:46:28 <hankuoffroad[m]> Yes, I'm willing to learn that one at a time :)
19:46:51 <darknao> or how to link to them? (you can't do that, partials are not document, it's just snippets that can be included in other pages)
19:47:11 <hankuoffroad[m]> how to refer back to the original text
19:47:37 <hankuoffroad[m]> They look more scary than code blocks.
19:48:04 <hankuoffroad[m]> If you could send me some links afterwards, I'll digest them
19:48:41 <darknao> the partials used here are just adoc files like any others: https://pagure.io/fedora-docs/quick-docs/blob/main/f/modules/ROOT/pages/_partials/con_package-management-in-fedora.adoc
19:48:42 <pboy> I am considering whether we should integrate the partials, at least in this case, into the text. It doesn't really make sense to me.
19:49:24 <hankuoffroad[m]> darknao: ok thanks
19:49:35 <darknao> you can edit them just like regular pages, but without adding any metadata to it like :authors: or :revnumber:
19:50:17 <darknao> #link https://docs.antora.org/antora/latest/page/partials/
19:50:56 <darknao> partials is useful when you want to use the same paragraph at various places in other document
19:51:12 <darknao> if it's only used once, it's not really worth it
19:51:37 <hankuoffroad[m]> Good to know, I'm well informed now
19:51:46 <AnthonyMcGlone[m> Same here. Cheers.
19:52:09 <pboy> darknao  yes, I think at least in this case it is not reusable.
19:52:54 <darknao> yes we should not overuse them, as it make reviewing the global document harder
19:53:57 <pboy> OK If hankuoffroad[m]  thinks it's easier or better to bring the partials back into the main text, he should do it.
19:54:07 <darknao> note that partials can be anything and not only asciidoc, or full paragraph of text
19:54:33 <darknao> it can just be a small piece of code block that you use several time in the same document
19:55:37 <hankuoffroad[m]> Make sense, thanks pboy darknao
19:55:54 <pboy> OK e #522 / grub 2
19:56:14 <pboy> AnthonyMcGlone[m  What do you think about my assessment that this is a guide rather than a howtio?
19:57:02 <AnthonyMcGlone[m> I concur with that assessment.
19:57:18 <darknao> +1
19:57:55 <AnthonyMcGlone[m> There was one thing I didn't understand. Moving it to "tools - administration". Is that in a different guide somewhere?
19:58:05 <pboy> OK, then that would be a candidate for moving to the admin tools box.
19:58:14 <pboy> Oh, too slow
19:58:20 <darknao> I have one question about this page
19:58:30 <pboy> AnthonyMcGlone[m> It a different systematic location.
19:58:41 <darknao> not related to the content, but to the format
19:58:42 <pboy> darknao go on
20:00:51 <darknao> I think this page is too long. What do you think about splitting it in a few small pages within the same "group"? For this kind of pages, we can enable pagination to make it easy for readers to parse it
20:01:19 <darknao> I think when the Table of Contents is too big to fit your screen, that probably mean the page is too long
20:01:55 <pboy> darknao +1!  If we move it to the tools guide, we should reformat it.  A big yes, it is too long.
20:02:19 <darknao> maybe we should say something like that in our future style guide
20:02:20 <pboy> And that is a problem for readability and positive UX
20:02:43 <darknao> I remember one page about rpm that we have here, it's way to long for anyone to read it
20:03:10 <pboy> Yes, I'm planning a text about quality and type of articles: hot-to, tutorial, guide, ....
20:03:31 <pboy> It goes back to worl of Anuschka Jain, our former intern.
20:03:43 <AlanBowman[m]> I sometimes break down long docs into "this is how to use it" and "this is how it works," which are very different things.
20:03:54 <pboy> And yes, with the rom article it is the same.
20:04:00 <darknao> https://docs.fedoraproject.org/en-US/packaging-guidelines/ for instance
20:04:43 <pboy> Oh, that's even worse.
20:05:25 <pboy> It badly needs improvement of readeability. :-)
20:05:54 <pboy> AlanBowman[m]. +!
20:06:59 <pboy> AnthonyMcGlone[m you said you would pick up another one. Do you already know, which one?
20:07:26 <AnthonyMcGlone[m> Yes, issue #522 just mentioned.
20:07:47 <pboy> Background: I want to ask on user list, if someone would help us with an article noone of us picks up
20:09:11 <pboy> OK, so we nobody for #524 so far?
20:10:45 <pboy> OK, no one calls „me", I will try it with this on user list.
20:11:02 <darknao> I have one last topic I wanted to bring up regarding quick docs before the end of the meeting
20:11:21 <darknao> and that is about the category/tag system
20:11:28 <pboy> OK, I'm finished with my questions
20:11:56 <pboy> darknao yes, I forgot.
20:12:10 <darknao> I think we should "curate" a set of categories that writers can use for their quick-docs
20:12:57 <darknao> for now, it's pretty much free for all, and it may become quickly out of hand if we let writers choose their own category names
20:13:16 <pboy> darknao yes, I would like to combine a curated list (categories) with a open list (tags)
20:13:23 <darknao> +1
20:13:44 <pboy> For categories, we could start with the navigation items.
20:13:46 <darknao> are we going to limit the number of tags an article can get?
20:14:17 <pboy> darknao I'm not sure, but I think that would be necessary, just in case.
20:14:27 <darknao[m]> btw, this is how category/tags looks on articles right now
20:14:28 * darknao[m] uploaded an image: (347KiB) < https://libera.ems.host/_matrix/media/v3/download/fedora.im/0fd63b0aa8f91343f2055fd94727ef0e6818d972/image.png >
20:15:05 <darknao> green is the category, blue are the tags
20:15:20 <pboy> darknao that's perfect !
20:15:37 <hankuoffroad[m]> that'll do
20:15:38 <darknao> clicking those tags/category will bring you to the category page with all the linked articles
20:15:48 <pboy> Probably a new line between categories and tags?
20:16:17 <darknao> I can do that
20:16:35 <pboy> And maybe a bit more white space between toc and the categories?
20:16:57 <pboy> The link makes it even better!
20:18:35 <pboy> I hope I can manage to start a guide: How to write a Quick Doc article this week.
20:18:56 <darknao> one last thing
20:19:26 <darknao> I remember you wanted to get rid of the navigation tree, and use category instead
20:19:50 <pboy> Yes, it's a suggestion of aday for a new design.
20:20:06 <darknao> does that mean that you want to remove the right navigation menu and only keep the category/tags on the left?
20:20:30 <darknao> or just replacing the navigation tree by a list of categories or something else?
20:20:44 <pboy> haven't thought through the details yet.
20:21:19 <darknao> ok, I don't need an answer today :) but just wondering how we want to be able to browse the quick docs
20:21:35 <pboy> I would love to get @adoc to collaborate. He had I the thread ideas that I liked very much.
20:21:50 <darknao> like search oriented, or change the landing page to display all categories, or ...?
20:22:32 <pboy> There was a thread about docs design, some weeks ago. I don't find it at the moment.
20:22:59 <darknao> months ago*
20:23:03 <darknao> #link https://discussion.fedoraproject.org/t/fedora-docs-design-work/40062
20:23:42 <pboy> Yes, I mean that. :-)
20:23:57 <pboy> whether weeks, or months, who cares ?  :-)
20:24:07 <hankuoffroad[m]> That looks neat
20:25:16 <pboy> A key point was: no central, rigid navigation, everything more fluid and to be seen in multiple perspectives.
20:25:48 <pboy> And short texts, all independent of each other.
20:26:52 <AlanBowman[m]> The fancy term for that is "every page is page one."
20:27:07 <AlanBowman[m]> There is actually a book about that concept by the same name.
20:27:17 <pboy> OK, we should block any numer > 1
20:27:26 <pboy> numer -> number
20:27:32 <pboy> :-)
20:28:11 <pboy> AlanBowman[m]. Do you have a link?
20:29:31 <AlanBowman[m]> https://everypageispageone.com/the-book/
20:29:45 <pboy> Thanks!
20:29:54 <AlanBowman[m]> I don't 100% agree with him on this, but it's a common topic in docs circles.
20:30:13 <AlanBowman[m]> I saw him give a talk on it at a conference in...2012, I think.
20:30:55 <hankuoffroad[m]> Added to my winter reading list
20:31:05 <pboy> At least, looks interesting
20:31:31 <darknao> alright, thanks everyone for today, this was a great meeting :)
20:31:55 <hankuoffroad[m]> thanks
20:32:06 <darknao> #endmeeting