docs
MINUTES
18:30:03 <pboy> #startmeeting docs
18:30:03 <zodbot> Meeting started Wed Jun 22 18:30:03 2022 UTC.
18:30:03 <zodbot> This meeting is logged and archived in a public location.
18:30:03 <zodbot> The chair is pboy. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
18:30:03 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
18:30:03 <zodbot> The meeting name has been set to 'docs'
18:30:13 <pboy> #chair pboy darknao
18:30:13 <zodbot> Current chairs: darknao pboy
18:30:21 <pboy> #topic Roll call
18:30:23 <darknao> .hi
18:30:24 <zodbot> darknao: darknao 'Francois Andrieu' <darknao@drkn.ninja>
18:30:31 <heidal[m]> .hi
18:30:32 <zodbot> heidal[m]: Sorry, but user 'heidal [m]' does not exist
18:30:33 <mateusrc> .hello mateusrodcosta
18:30:34 <zodbot> mateusrc: mateusrodcosta 'Mateus Rodrigues Costa' <mateusrodcosta@gmail.com>
18:31:04 <py0xc3[m]> .hi py0xc3
18:31:05 <zodbot> py0xc3[m]: Sorry, but user 'py0xc3 [m]' does not exist
18:31:23 <heidal[m]> .hi hankuoffroad
18:31:24 <zodbot> heidal[m]: Sorry, but user 'heidal [m]' does not exist
18:31:48 <mateusrc> Maybe you guys should try `.hello` as well?
18:32:02 <heidal[m]> .hello hankuoffroad
18:32:03 <zodbot> heidal[m]: hankuoffroad 'None' <allegrovelo@gmail.com>
18:32:33 <pboy> seems that worked.
18:32:50 <py0xc3[m]> .hello py0xc3
18:32:51 <zodbot> py0xc3[m]: py0xc3 'Christopher Klooz' <py0xc3@my.mail.de>
18:32:59 <py0xc3[m]> Interesting
18:33:18 <mateusrc> As far as I understood `.hi` uses the IRC nickname you are using and `.hello` takes your FAS id as parameter
18:34:23 <mateusrc> And Matrix changes has the suffix on your IRC nick, which seems to break `.hi`
18:34:26 <py0xc3[m]> Previously both worked, last week .hi did not but in the minutes, I was correctly stated. Whatever ;)
18:34:40 <pboy> OK.  Welcome everybody!
18:34:45 <py0xc3[m]> Hi
18:34:48 <pboy> Darknao and I will try to represent bcotton as good as possible
18:35:02 <pboy> I'll post the agenda now
18:35:11 <pboy> #topic Agenda
18:35:19 <pboy> #info Announcements
18:35:27 <pboy> #info Review action items
18:35:35 <pboy> #info Contributors guide rough draft
18:35:49 <pboy> #info How to proceed to develop contributors guide / team page
18:35:58 <pboy> #info style guide proposal
18:36:06 <pboy> #info how to proceed with old-docs
18:36:15 <pboy> #info Open floor
18:36:33 <pboy> Anything I forgot?
18:36:45 <pboy> Or anything else we should discuss?
18:37:14 <darknao> looks good
18:37:17 <pboy> OK, none
18:37:25 <pboy> #info Announcements
18:37:34 <pboy> I suppose:
18:37:42 <pboy> #help Some release notes still need written: https://discussion.fedoraproject.org/t/how-to-write-fedora-release-notes/38311
18:37:59 <pboy> And still, until we decide about and updated procedure
18:38:07 <pboy> #info We're using the docs-fp-o repo to track meta-work
18:38:17 <pboy> #link https://pagure.io/fedora-docs/docs-fp-o/issues
18:38:25 <pboy> Any other announcements to make?
18:38:44 <darknao> nothing here
18:38:46 <pboy> I didn't find any open action from last meeding
18:38:58 <pboy> PK
18:39:02 <darknao> there were a few
18:39:07 <pboy> #topic Previous action items
18:39:18 <pboy> I suppose, we still have:
18:39:18 <darknao> #info pbokoc was to finally add a relnotes guide to the contributor docs
18:39:22 <darknao> #info bcotton was to draft Docs Team Charter
18:39:34 <darknao> #info darknao was to configure the remaining repos in GitLib for CI
18:40:20 <pboy> I think the former 2 are still open
18:40:31 <darknao> right, and mine is still in progress
18:40:56 <pboy> OK, so we'll action as again for the books.
18:41:14 <darknao> i've set up CI on one more repository: https://gitlab.com/fedora/docs/fedora-linux-documentation/fedora-linux-dnf-guide but I will come to that later
18:41:26 <pboy> #action pbokoc is  finally add a relnotes guide to the contributor docs
18:41:46 <pboy> #action cotton is ongoing to draft Docs Team Charter
18:42:10 <pboy> OK, next topic?
18:42:36 <pboy> #topic Contributors guide rough draft
18:42:48 <pboy> #link https://discussion.fedoraproject.org/t/improving-docs-team-page-step-2-of-n/39949
18:43:06 <pboy> Any comments to the draft?
18:44:09 <pboy> I see none
18:44:15 <pboy> Next step is to transform the ideas from the thread above into a set of asciidoc pages.
18:44:26 <pboy> If no one else wants to take this on, I could do that as soon as we have decided about how to do the pages development (next topic)
18:44:49 <pboy> Does someone take it?
18:45:14 <darknao> i have one comment/question
18:45:32 <pboy> go on
18:45:57 <mateusrc> pboy: I could try
18:45:58 <darknao> in the content contributions section, what's the differences between Using file edit interface and local writing environment?
18:46:09 <heidal[m]> pboy: Re. How to contribute (page), I would work on the content draft.
18:46:10 <AnushkaJain[m]1> Hi everyone! As I'm working on the website revamp during my Outreachy Internship, I started with sorting out the entire content on the docs website.... (full message at https://libera.ems.host/_matrix/media/r0/download/libera.chat/7240bf6d8fc25c63b767bda06fd0bf4a1cbfb449)
18:46:41 <pboy> OK, one after the other :-)
18:47:15 <pboy> darknao with file edit interface I mean the option on the gitlab page
18:47:34 <darknao> that's not the Using web interface one?
18:47:40 <pboy> with local writing the clone workflow with a local environment
18:48:01 <pboy> darknao, no that are 2 different options.
18:48:20 <pboy> the file edit, the can just edit one file, nothing else
18:48:36 <pboy> and the pull request etc. is then automatically done.
18:50:30 <pboy> darknao  OK?
18:50:56 <darknao> ok, maybe that should be reworded a little then, because I'm not sure it's very clear as it
18:51:29 <pboy> yes, we should check and probably use the wording in den gitlab UI.
18:51:45 <darknao> in the way I see it, both file edit interface and web interface are use, well, a web interface
18:51:49 <mateusrc> > <@likeanushkaa:matrix.org> Hi everyone! As I'm working on the website revamp during my Outreachy Internship, I started with sorting out the entire content on the docs website.... (full message at https://libera.ems.host/_matrix/media/r0/download/libera.chat/cc4124026b1b0439b0cc6bace2b3302c0123e7da)
18:52:14 <mateusrc> (But that's just my personal experience)
18:52:22 <heidal[m]> pboy: WebIDE and fork (quick edit)
18:54:24 <pboy> well, there are to options "find file" and "Web ide"  With the former I could edit just one file, with the letter I got a complete web based ide.
18:54:42 <pboy> letter -> latter
18:55:38 <darknao> got it
18:55:41 <AnushkaJain[m]1> > <@MateusRodCosta:matrix.org> IMHO, generally I never really considered the Fedora Docs very useful unless I needed info for something Fedora-specific. If I want info on relatively new Linux stuff I generally use Arch Wiki.
18:55:41 <AnushkaJain[m]1> > I guess Fedora Docs being a bit out-of-date and confusing might not help me to consider it over the Arch Wiki unless I have no choice.
18:55:41 <AnushkaJain[m]1> Oh I see that. I guess I wanted to model it around Fedora-specific content more than generic content. Although I'm a real rookie to understand the difference in the value of content between Fedora Docs and Arch wiki!
18:57:06 <pboy> AnushkaJain yeah, please wait a moment.  Let's first finish the contributor page and team page
18:57:44 <mateusrc> AnushkaJain[m]1: If you think the idea the idea of Fedora being "First" to adopt new technologies, then there's actually not much difference, but the Arch wiki is a wiki that can be edited by anyone, it doesn't need to follow the rules that actual official documentation would have.
18:58:19 <pboy> heidal[m] Didn't you want to write the doc about the web ide?
18:58:24 <darknao> yes, let's discuss this during the open floor
18:59:20 <pboy> OK, we move the discussion initiated by AnushkaJain to Open floor.. And we hurry to get there.
18:59:28 <heidal[m]> pboy: Yes, I'm working on it. I figured out the differences between 'find file' and 'WebIDE'. We need an up to date article on gitlab ui
18:59:41 <pboy> good Idea.
18:59:56 <pboy> So i "action" you
19:00:09 <heidal[m]> agreed
19:00:46 <pboy> #action heidal[m] to write a draft about usage of gitlab web ide for content contribution.
19:00:56 <pboy> So, lets hurry
19:01:10 <pboy> #topic How to proceed to develop contributors guide / team page
19:01:17 <pboy> #link https://discussion.fedoraproject.org/t/staging-environment-for-contributor-guide-team-page/40015
19:01:41 <pboy> I think that is clear. We use a feature branch as suggestged by darknao
19:02:16 <pboy> And we use the gitlab web page for a first round of discussion.
19:02:31 <pboy> Any comment about that?
19:02:32 <darknao> as an exemple for the preview thing, you can take a look at this MR: https://gitlab.com/fedora/docs/fedora-linux-documentation/fedora-linux-dnf-guide/-/merge_requests/2
19:03:00 <darknao> you'll see a "Deployed to preview xxx" in the middle
19:03:09 <darknao> and a "View App" link
19:03:18 <mateusrc> pboy: I actually don't think I got what is being talked here at all
19:03:19 <darknao> that will brings you to the preview site
19:03:39 <mateusrc> Is it like "A branch is pushed and CI will create a preview available at this URL"?
19:04:31 <pboy> darknao got it looks fine.
19:04:34 <mateusrc> Ah, seems to be that, got it
19:05:08 <pboy> OK, so we use that for the first steps. And look how far we get with it.
19:06:08 <pboy> #agreed We use the gitlab generated preview for the first development and discussion of contributor pages
19:06:32 <pboy> #topic style guide proposal
19:06:42 <pboy> #link https://discussion.fedoraproject.org/t/fedora-documentation-style-guide-1st-draft-proposal/39961
19:06:51 <pboy> #link https://docs.fedoraproject.org/en-US/fedora-docs/contributing/style-guide/
19:07:43 <pboy> AnushkaJain made a proposal about admonitions as we discussed previously.
19:07:59 <pboy> I would like to add it.
19:08:25 <pboy> Any comments or additions here?
19:08:33 <darknao> yep
19:08:55 <pboy> go on
19:10:02 <darknao> the website team is asking if we have some plan to include an coding style guide for documentation. Something about asciidoc rules to use for instance like line width..
19:11:30 <darknao> it's not really a writing style per say, but more about the right way to write asciidoc code
19:11:46 <pboy> II once thought about whether we might need something to vary the spacing between bullet lists.
19:12:14 <pboy> Well, "the right way to write asciidoc code" is worth a documentation.
19:12:31 <mateusrc> pboy: I kinda like it, although I kinda don't understand the italics example, seems nothing is italiczed for me
19:12:35 <darknao> something like this: https://asciidoctor.org/docs/asciidoc-recommended-practices/
19:12:41 <darknao> but tailored for us
19:13:31 <pboy> Don't we have a extra page about ascii doc formatting?
19:13:48 <pboy> I would like to have something like that example!
19:14:13 <darknao> we do have an extra page
19:14:15 <darknao> https://docs.fedoraproject.org/en-US/fedora-docs/asciidoc-fedora/
19:14:28 <darknao> but it's very light
19:14:41 <pboy> indeed. :-)
19:15:14 <pboy> So we should fill that, or? Would be great.
19:15:35 <darknao> I think that can be valuable yes
19:15:45 <pboy> mateusrc the text is still a bit rough and has to be fine tuned.
19:16:22 <darknao> and maybe we should work with the website team since they are interrested in this
19:16:32 <pboy> darknao: lets that make an agreed for upcomming work planning.?
19:16:43 <pboy> could you make the wording?
19:18:20 <darknao> you mean working on the coding style?
19:19:01 <pboy> yes, we plan to take the idea of the coding style into the asciidoctor page
19:20:10 <pboy> mateusrc I would make a refined version of the style guide, would you than review it and improve it?
19:20:30 <darknao> sounds good
19:20:39 <mateusrc> pboy: Sure
19:21:46 <pboy> #agreed we will improve the current asciidoc page with an elaborated coding style guide.
19:22:11 <pboy> #agreed mateusrc. will review the style guide proposal
19:22:39 <pboy> So let's switch to Open Floor so we have time to discuss.
19:23:06 <pboy> no, we still have
19:23:15 <pboy> #topic how to proceed with old-docs
19:23:46 <pboy> proposed: we postpone that to next meeting. Or is it somehow urgent?
19:23:52 <darknao> that can wait
19:24:09 <pboy> #agreed postpone this topic to next meeting
19:24:20 <pboy> #topic Open Floor
19:24:20 <py0xc3[m]> Can wait
19:25:20 <pboy> OK, AnushkaJain[m]1 your part. :-)
19:26:14 <AnushkaJain[m]1> > <@likeanushkaa:matrix.org> Hi everyone! As I'm working on the website revamp during my Outreachy Internship, I started with sorting out the entire content on the docs website.... (full message at https://libera.ems.host/_matrix/media/r0/download/libera.chat/3e3b85dd5ff28dc8a286b68da4d9446570372015)
19:27:41 <pboy> OK, let's help in this case.
19:28:29 <mateusrc> <mateusrc> "If you think the idea the idea..." <- I should also quote this again
19:29:37 <pboy> I think, Trying to sort the entire content is a hard work and s hardly manageable in a reasonable time frame
19:29:38 <AnushkaJain[m]1> I'm also confused whether I should somehow test the designs I made during the contribution period, o work on the process of defining an information architecture for the site..
19:30:23 <pboy> That depends on your working plan.
19:30:41 <AnushkaJain[m]1> pboy: That is true, I'm kind of wondering what would drive the design decisions behind the front page redesign.
19:30:57 <AnushkaJain[m]1> s/o/or/
19:32:03 <pboy> Did you read the post by Alan Day about Fedora docs design work?
19:32:31 <AnushkaJain[m]1> yes, I did, today!
19:33:03 <pboy> I guess, the redesign of the front page is currently so unclear, it would be very hard for you to work on that.
19:33:21 <pboy> If I remeber, your internship is 3 months?
19:34:34 <AnushkaJain[m]1> pboy: Yes!
19:34:42 <pboy> I suppose, the process to redesign the front page takes more than 3 months.
19:35:34 <pboy> Therefore my suggestion some weeks ago to choose something like QuickDocs, that is manageable.
19:36:02 <AnushkaJain[m]1> AnushkaJain[m]1: Also, I found an interesting anecdote from that- "User and contributor docs were generally separate. This seemed to help clarify the goal, scope and structure of each documentation site."
19:36:02 <AnushkaJain[m]1> When I visited Fedora Docs for the first time I didn't understand the 2 different headers there were!
19:36:02 <AnushkaJain[m]1> Right now I hadn't even thought from this perspective of users, and hence the survey as well..
19:36:45 <pboy> Well, that is a matter of discussion.
19:37:10 <pboy> That are 2 areas, but are they differfent in terms of design? I doubt that.
19:37:22 <pboy> Well, I see our time is up.
19:38:10 <pboy> AnushkaJain[m]1 you shoud discuss the goal ot the intenship with Ben. I would like to contribute and get involved.
19:38:20 <py0xc3[m]> Maybe switch to the Docs channel if there is still something to clarify
19:38:22 <pboy> And would help in that matter
19:38:37 <pboy> py0xc3[m] +1
19:38:41 <AnushkaJain[m]1> Sure!
19:39:08 <pboy> OK, I close the meeting and we switch to the IRC doc channel.!
19:39:20 <pboy> Thanks for comming.
19:39:26 <py0xc3[m]> See you there
19:39:30 <pboy> Was a very productive meeting
19:39:34 <py0xc3[m]> Thanks for organizing
19:39:42 <AnushkaJain[m]1> Thankyou!
19:39:51 <pboy> #endmeeting