08:57:06 #startmeeting Fedora Documentation FAD 2018 08:57:06 Meeting started Mon Feb 26 08:57:06 2018 UTC. The chair is jwf. Information about MeetBot at http://wiki.debian.org/MeetBot. 08:57:06 Useful Commands: #action #agreed #halp #info #idea #link #topic. 08:57:06 The meeting name has been set to 'fedora_documentation_fad_2018' 08:57:08 #meetingname fedora_docs 08:57:08 The meeting name has been set to 'fedora_docs' 08:57:26 #topic Work session 08:57:38 I thought this could be useful for keeping tabs of links or other #info bits 08:58:06 #link https://pagure.io/fedora-docs-container 08:58:39 #chair bexelbie jsmith ryanlerch rkratky mayorga 08:58:39 Current chairs: bexelbie jsmith jwf mayorga rkratky ryanlerch 08:58:55 #topic Workflow 08:59:02 #undo 08:59:02 Removing item from minutes: 08:59:05 #topic Topics 08:59:09 #info Conversation on git 08:59:20 #info Introducing AsciiDoc 08:59:26 #info Introducing AsciiBinder 08:59:43 Not wanting to discourage people from learning AB, but you don't need to learn it 09:00:04 #info Workflow / repo structure 09:00:15 #info Quick-docs vs. books 09:00:45 #info Modular docs intro (?) 09:00:55 #topic Workflow / repo structure 09:01:24 #link https://pagure.io/fedora-docs 09:01:38 #info This is mostly a reference repo; used so we can complete that URL 09:01:47 #link https://pagure.io/fedora-docs/docs-fp-o 09:01:58 #info docs-fp-o is master docs repo 09:02:14 #info All CSS and other content (ryanlerch helping with this) 09:02:25 #info Builder script that actually builds all the docs 09:02:37 #info Old book format: en-US 09:02:54 #info _topic-map.yml is where you list all things that actually should be published 09:02:59 Pretty basic 09:03:01 It's YAML 09:03:09 give it a directory name, list topics that can be published 09:03:20 Who knows what YAML is? (hand raise) 09:03:32 YAML is mostly self-explanatory, whitespace matters, etc. 09:03:54 Contrasting the _topic-map.yml for release notes: 09:04:15 #info Fedora Release Notes > Book Information > Welcome to Fedora 09:04:53 #link https://pagure.io/fedora-docs/release-notes/blob/master/f/_topic_map.yml 09:05:56 #link https://docs.fedoraproject.org/f27/release-notes/index.html 09:06:03 #info File name doesn't have to match menu name 09:07:11 We can create aliases in the _topic-map.yml too 09:07:13 As a note 09:09:07 #info Test changes locally for any content repo (i.e. a repo that holds AsciiDoc pages, not the whole shebang) 09:09:19 #info Builds piece of the docs locally, not EVERYTHING 09:09:50 #idea Focus on content – things like CSS may be out of sync in content repos. Don't worry about it. Focus on content. 09:10:30 #info === Branching === 09:10:41 #info Think about the work you're doing and the context of the latest version of Fedora 09:10:48 #info Less value in fixing something in f26 vs. f28 09:10:58 #info Every repo has master branch – represents Rawhide 09:11:08 #idea Represents latest version of the docs and what we want to ship 09:11:23 #nick docs-writers 09:11:39 #action docs-writers Target working on master branch / latest version as much as possible 09:12:28 Q: Can I fork fedora-docs? 09:12:47 A: No, you don't need to – clone specific content repo. Unless you want to add to the README… 09:14:35 Talking a bit about git branching workflow 09:15:41 #info Some repos will only ever have a master branch (Council docs, CommOps docs, etc.) 09:17:05 If you want to keep working in a repo, rebasing is a good habit 09:17:17 bexelbie: "Most of you claimed to know git, but if you need help, we're happy to help" 09:17:34 (I won't spend much time transcribing git discussions) 09:18:02 #topic Issues 09:18:14 #info File issues / tickets for content in the individual repos 09:18:24 #info Builder issues / tickets go to builder repo (docs-fp-o) 09:21:50 #idea Community repo for tickets / issues: Not considered yet, but will revisit? 09:21:52 Triage 101? 09:23:08 #help People still file bugs in Bugzilla… need to work on publicity for that 09:24:21 #topic Problems we have today 09:24:31 #info Creating internal links 09:24:38 I missed some of this, bexelbie can expand ^^) 09:25:00 #info Images must be in images subdirectory to render 09:25:23 #chair coremodule 09:25:23 Current chairs: bexelbie coremodule jsmith jwf mayorga rkratky ryanlerch 09:25:38 #chair x3mboy 09:25:38 Current chairs: bexelbie coremodule jsmith jwf mayorga rkratky ryanlerch x3mboy 09:26:56 #action docs-writers Use smaller images whenever possible – AsciiBinder base64's images and renders them in HTML. Images should be small. (fixed someday??) 09:27:28 I don't know IRC nicks well, so if you're in the room and not chaired, let me know 09:28:16 #topic Style guide 09:28:21 #info Something we don't have but want to work on 09:28:42 #action docs-writers Please use ATX style for now (i.e. headers preceded by equal signs instead of underlining text) 09:29:14 #action docs-writers One sentence per line (makes diffs look REALLY nice, but weird to read) 09:30:06 #idea If you have a really long sentence, it will be obvious. Easier to know when you need to simplify language. Translations team easier to work this way. 09:30:19 DON'T DO IT (to second-language speakers / translators) 09:30:41 #action docs-writers Use small images when possible (see caveat above) 09:31:15 #help If you need help or have questions on styling, please ask when they come up. Remotees can ask in this channel during FAD. 09:32:31 #topic Modular docs (preview) - rkratky 09:32:49 #info Potential in quick-docs for modular docs: individual things people want to do in Fedora 09:33:18 #info Modularization: Common, repeating text across files (intro, installing RPMs, other generic info); write once and over and over 09:33:48 #idea Think of docs modularity as word recycling or duplicating blocks of code 09:34:06 #info rkratky to give intro on how to do this later on in FAD… stay tuned! 09:34:25 Q: Do they need to exist in repo or can be cross-referenced? 09:34:29 A: Eventually, but not there yet 09:36:13 #topic Entities - bexelbie 09:37:49 #link https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/en-US/entities.adoc 09:37:51 #chair langdon 09:37:51 Current chairs: bexelbie coremodule jsmith jwf langdon mayorga rkratky ryanlerch x3mboy 09:38:33 #idea Entities are variables you can reuse across docs 09:38:48 Example above in sysadmin-guide 09:39:12 #link https://pagure.io/fedora-docs-container a handy command to do asciibinding within a docker container 09:39:40 #topic Break 09:40:21 #undo 09:40:21 Removing item from minutes: 09:40:24 #link https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/en-US/basic-system-configuration/Configuring_the_Date_and_Time.adoc#_3 09:43:16 #chair mattdm 09:43:16 Current chairs: bexelbie coremodule jsmith jwf langdon mattdm mayorga rkratky ryanlerch x3mboy 09:48:08 #chair Srijita 09:48:08 Current chairs: Srijita bexelbie coremodule jsmith jwf langdon mattdm mayorga rkratky ryanlerch x3mboy 09:48:31 #topic Break 09:49:07 Also, anyone else hanging out in channel, feel free to link things or add #info if I miss something 09:51:10 * asamalik[m] waves 09:51:16 * jwf waves to asamalik[m] 09:51:19 #chair asamalik[m] 09:51:19 Current chairs: Srijita asamalik[m] bexelbie coremodule jsmith jwf langdon mattdm mayorga rkratky ryanlerch x3mboy 09:54:44 I think this will be covered in the AsciiDoc intro in a bit, buuut this was helpful for me: https://asciidoctor.org/docs/asciidoc-recommended-practices/ 10:02:22 We're about to launch back in! 10:02:25 AsciiDoc intro 10:04:44 #topic Introduction to AsciiDoc 10:04:52 Q: How familiar are you all with ADoc? 10:04:59 Abbreviating AsciiDoc => ADoc from here on 10:05:29 A: Mixed response throughout room, from novice to well-versed 10:05:46 #info AsciiDoc: Lightweight markup language, a helpful quick reference page online 10:05:53 #link https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ 10:06:49 Uses tags for styling 10:07:15 #info Whitespace matters (e.g. list items must be separated by whitespace) 10:07:24 #info Lets you create various types of docs - we use it for books 10:07:32 #info Also works for man pages, articles, etc. 10:07:44 #info === How it's built === 10:07:50 #info AsciiDoctor most commonly used to build it 10:08:39 AsciiDoc originally in Python, no longer maintained; can revisit later 10:08:45 (revisit the differences) 10:09:24 ^^ to that point: https://github.com/asciidoctor/asciidoctor/blob/master/compat/asciidoc.conf 10:10:12 #info We have a AsciiDocTutorial repo but it's currently internal – will make public during FAD 10:11:11 #info H1 value is a title of book / doc – only one H1 value per ADoc 10:12:14 #info Use Unicode characters 10:13:29 #info Q: Square brackets at end of include directive? [] 10:14:22 #info A: Square brackets often used. For include directive, you can make config changes (e.g. `leveloffset=+1`) 10:15:20 #info BE CAREFUL about config changes; some things are friendly for AsciiDoctor, but we're using AsciiBinder in Fedora. Keep it simple and plain AsciiDoc when possible. 10:16:00 cverna, I haven't forgotten about you yet - we are just going through front matter here 10:17:09 bexelbie: no problem, I am doing some other background task and try to follow things here too :) 10:18:39 #info How to understand difference from AsciiDoctor and AsciiBinder: AsciiDoctor has a master doc that you include and concatenate all docs into; AsciiBinder does not do this. 10:19:23 tl;dr: AsciiBinder AsciiBinder AsciiBinder 10:19:56 #info === Basic markup === 10:20:18 #info Most of the "basics" are online in the quick reference 10:20:23 #link https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ 10:20:43 For meeting log purposes, I'm not going to document anything that doesn't seem unusual to me, and for basics, anyone can reference the link above 10:20:51 In FAD, we're taking a quick walkthrough 10:24:55 #action docs-writers Be consistent! Whatever you do for styling, be consistent with what you use 10:26:53 #info AsciiDoc has a limit of four levels for ordered lists 10:26:55 #undo 10:26:56 Removing item from minutes: INFO by jwf at 10:26:53 : AsciiDoc has a limit of four levels for ordered lists 10:27:00 #info AsciiDoc has a limit of five levels for ordered lists 10:27:05 mattdm++ for the catch 10:27:30 HOWEVER, try to avoid going to that many sub-levels anyways… too many can be hard to read / follow 10:28:23 #info Create ordered lists with periods (nifty – if you've used other markup languages, this is a simple and effective way for ordered lists) 10:29:40 #link 10:29:45 #undo 10:29:45 Removing item from minutes: 10:30:44 #info Checklists are also natively supported. We don't use them often in Fedora Docs proper, may be useful for some sub-projects 10:30:48 #link https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#horizontal-rules-and-page-breaks 10:31:06 #info Labeled lists do not go into the table of contents 10:31:24 Labeled lines is nice 10:31:47 Compare to ReStructuredText, labeled lines are like note:: or warning:: blocks 10:31:51 Nifty 10:33:15 #info Q&A section also natively supported!! 10:33:36 #info AsciiBinder uses AsciiDoctor to render AsciiDoc 10:34:26 #info We're spending a lot of time on AsciiDoctor vs. AsciiBinder because there are similarities and differences that have subtle impacts. We may hit more snags as we go but be aware that the things you read online may not always work if it's specific to AsciiDoctor 10:35:19 < insert AV troubleshooting steps here > 10:36:17 bexelbie: Hope the last two #info lines are accurate. ^^ 10:38:36 yes, it is 10:38:40 I am working on a list 10:38:55 Cool, thanks 10:39:18 #info Literal blocks support syntax highlighting with a line above them, e.g. [source,bash] 10:39:27 To be obnoxious, going to type it out in IRC 10:39:31 [source,bash] 10:39:32 ---- 10:39:39 $ echo "Hello world" 10:39:41 ---- 10:40:46 #info Literal blocks can also inherit entities (e.g. [source,bash,subs="attributes+"]), but you have to explicitly call them (otherwise, it renders as plaintext) 10:47:09 #info Paragraphs: Whitespace between paragraphs required; whitespace between headers and body text encouraged 10:50:22 #info + signs are a way to render soft returns in the text; must be placed at end of line in source doc 10:50:51 #info === Tables === 10:52:40 #link https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables 10:53:51 #info jwf is super-enthused about how pretty the tables are 10:54:06 ^^ how pretty they are to write!!! 10:54:23 #info But beware translation woes: Tables are hard to translate and different languages order text differently 10:54:35 #idea Complex tables will (likely) never be translated 10:58:10 #info Think of the information you are presenting and what is the best way to present that 10:58:56 #info Docs philosophy wisdom from bexelbie: "If you are using four sublevels of bullets or tables, you may be presenting the info wrong." 10:59:38 #info There will always be edge cases for tables and lots of sublevels (so you don't have to ignore them), but give a thought about whether a table is best before you put something in a table 11:02:42 #info remember almost no manpages need a table :D 11:03:23 true… hadn't thought of that 11:03:36 #info === Admonition blocks === 11:03:56 #info In English? Special blocks of text that get icons (e.g. an info icon, light bulb, FontAwesome icons in general) 11:04:14 #link https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#more-delimited-blocks 11:04:24 * jwf is away from keyboard for 5mins 11:13:02 I think we're starting to wrap up the intro 11:16:32 I just found a linter that supports AsciiDoc and you might find useful: https://github.com/ValeLint/vale 11:18:23 mayorga++ Nice!! 11:18:23 jwf: Karma for mayorga changed to 1 (for the f27 release cycle): https://badges.fedoraproject.org/tags/cookie/any 11:18:25 #link https://valelint.github.io/docs/ 11:19:18 mayorga++ 11:19:18 mattdm: Karma for mayorga changed to 2 (for the f27 release cycle): https://badges.fedoraproject.org/tags/cookie/any 11:19:33 https://budget.fedoraproject.org/budget/docs/faq_entries.html 11:19:37 #action bexelbie hey let's integrate that into the CI PR workflow 11:19:42 #undo 11:19:42 Removing item from minutes: ACTION by mattdm at 11:19:37 : bexelbie hey let's integrate that into the CI PR workflow 11:19:51 #action bexelbie hey let's integrate valelint into the CI PR workflow 11:22:22 mayorga: No package for Fedora… maybe something to get packaged. :D I've never packaged for Golang before 11:22:36 mattdm: That would be *really* cool 11:23:45 #info Callouts are a handy way to annotate literal blocks: see quick reference docs for details on how to do this 11:25:37 As a note, we're wrapping up this bit now, and will get lunch shortly 11:25:41 So will probably take a longer break 11:25:54 And then reconvene in an hour…? I'll confirm that in a sec 11:26:45 #meetingtopic Fedora Documentation FAD 2018 - Day 1 11:28:19 ok.. the container should be working pretty well now.. but your user must be 1000:1000 if you don't want to mess with perms.. 11:28:29 after lunch, i will look at making a shell script that will "do the right thing" with perms 13:19:52 #topic Lunch break 13:26:48 #topic Hack Time! 13:27:36 #info Folks are breaking out into small groups when needed (i.e. a quick git workflow session) or working on writing new docs / porting old ones 13:28:09 Remote attendees, either bexelbie or mattdm (or others in the channel) could advise on ways you can participate. 13:28:17 I'm jumping into the CommOps team docs 13:29:26 Is packaging this a valuable use of FAD time? https://github.com/ValeLint/vale 13:32:12 Please put what you're working on here: http://etherpad.osuosl.org/fdocs2018 13:44:12 #link http://etherpad.osuosl.org/fdocs2018 14:04:59 bexelbie, is it okay to write about any app which can be installed from RPM fusion ? like lets say VLC? 14:06:14 TIL: Vim doesn't recognize adoc as a filetype, only asciidoc 14:06:34 sumantro_: I see bexelbie and mattdm are not in the room. 14:06:48 langdon: Do you have opinions from a Council POV to sumantro_'s question? 14:07:29 jwf: sumantro_ i am fairly sure we talk about things from "other repos" .. like the "how to install flash page" 14:07:33 so i think it would be ok 14:07:52 That's what I was thinking too. Even the same with Chromium and Chrome 14:08:40 thanks langdon and jwf , as i read though the chrome page , its almost blank and I wanted to have your views and thoughts :) 14:10:03 My perspective on it is that Fedora makes a conscious decision to not include proprietary software in our distribution, but also recognize that there are unique needs for different use cases. I think writing docs for common tasks like this is a good idea. I don't think we should make it harder for people to use Fedora. 14:11:56 I think it's different to commit developer time and effort to packaging proprietary software in our distribution versus committing time to tell users how to use something that someone else has created and packaged elsewhere 14:12:05 Maybe an obvious disclaimer that this software is not offered by Fedora / Red Hat 14:13:18 On another note, I have an entity question – does it make sense to make some base URLs as entities in a doc? 14:13:27 if you're covering rpmfusion then please also cover the negativo17 nvidia driver repo (+ an explanation of what an akmod is and why you want that). It's incredibly helpful for nvidia users 14:13:33 For example: https://fedoraproject.org/wiki => $WIKI/CommOps 14:13:55 jwf, I've seen that done before but I never found it particularly useful 14:14:00 pbokoc: Definitely a +1 from me there… I'd love to link this in the Fedora Telegram group when this topic comes up every week 14:14:13 pbokoc: Interesting, any reason why not? 14:15:08 sumantro_: Oh, there is an :experimental: tag I saw mentioned earlier, but I don't have any context on it. Maybe we could label pages like that as :experimental:, but need clarification on what that's for / what it actually means 14:16:07 jwf, well I can only think of two reasons it could potentially be useful: 1) if whatever you're linking to (e.g. the wiki) changes domains - but that's incredibly unlikely, and even if it did happen, mass search and replace fixes that in like 3 seconds 14:17:55 and 2) if you're reusing docs between two projects which both have a wiki (or a bug tracker, whatever) - but even then an entity isn't hugely useful because you're unlikely to need an URL for that a whole lot of times, typically you just need to use it once per document for some kind of disclaimer that says "report bugs at ", so an entity doesn't really help anyway 14:21:03 pbokoc, I will try to! 14:21:22 sumantro_, coolio :) 14:23:21 ok.. the shell script & docker container is working well now: https://pagure.io/fedora-docs-container 14:26:09 sumantro_: see https://fedoraproject.org/wiki/Third_party_repositories 14:26:40 any pages like that need a disclaimer at the top specifical including the phrase "These software repositories are not officially affiliated or endorsed by the Fedora Project. Use them at your own discretion." 14:26:54 I'd also like to add "Fedora recommends the use of free and open source software and avoidance of software encumbered by patents." 14:28:02 sumantro_: I am making an entity. stand by. :) 14:34:19 mattdm, thanks :) 14:35:37 pbokoc: My use case is for Fedora sub-projects. I'm frequently linking internally to the Fedora wiki for pages related to a sub-project or other Fedora-centric content. I think in my use case, an entity makes sense for the wiki URL? 14:36:27 I was typing the wiki URL string over and over, so I thought entities could be a better way 14:37:06 jwf, yeah, that's true, it could save you some typing or copypasting if you're adding a lot of links 14:45:30 mattdm bexelbie , i see a kernel page , I was thinking of writing one on Kernel Testing , is that going to look good as a separate document or just extend the same kernel.adoc? 14:47:23 asamalik[m]: so where is your container? 14:50:04 sumantro_, depends on the content on the kernel 14:50:25 page 14:50:29 if it is logical to extend, let's do it 14:50:47 but I could easily see this being in the Fedora QA repo because it is specific to testing 14:53:23 asamalik[m]: ANSWER ME!! 14:53:27 sumantro_, does this work well? 14:53:36 I mean answer for you? 14:53:50 yes bexelbie 14:54:19 bexelbie, can you help me with the publishing part of QA join page :) 14:54:20 langdon: HERE!!!!! https://github.com/asamalik/asciidoc-dev-server 14:54:24 :P 14:54:31 * langdon covers his ears 14:55:37 Does someone have the string for permanent wiki redirects on hand? 14:55:45 I didn't write it down but know I'll need it later 14:55:53 Might be helpful for an #info block too 14:56:01 * asamalik[m] coughs as it hurts, feels apologetically 14:56:37 jwf, {{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}} 14:56:44 sumantro++ 14:56:46 jwf: Karma for sumantro changed to 4 (for the f27 release cycle): https://badges.fedoraproject.org/tags/cookie/any 14:57:12 #info How to SEO-magically redirect a wiki page into a docs page: {{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}} 14:57:21 .thank sumantro_ 14:57:21 jwf thinks sumantro_ is awesome and is happy they are helping! (Please don't forget to sumantro_++ also) 14:57:41 asamalik[m], ping is this accurate? author: Fedora Modularity 14:58:15 jwf, thanks :) 15:08:30 .moar food sumantro_|dinner 15:08:30 here sumantro_|dinner, have some more food 15:08:40 Don't forget, bexelbie asked for pictures ;-) 15:09:26 :P 15:21:54 bexelbie: here's a README for the s2i builder; https://pagure.io/fork/bstinson/fedora-docs/docs-fp-o/blob/add-dockerfile/f/openshift/README.md 15:33:09 this is my life, find out I can't come to the FAD and then get email after email reminding me that I could be in one of my favorite cities in the world right now. 15:49:35 .thank zoglesby 15:49:35 jwf thinks zoglesby is awesome and is happy they are helping! (Please don't forget to zoglesby++ also) 15:49:41 You're here with us in spirit :-) 15:49:50 Adding this to the wiki-to-docs wishlist: https://fedoraproject.org/wiki/Planet 15:55:07 ok.. now my script does everything asamalik[m] 's does .. plus all asciibinder commands! 15:56:04 collaboration work! 15:56:14 s 15:58:17 jwf: I'll take a look into packaging it… I have done some Golang packaging before. 15:58:41 langdon++ asamalik++ Nice! 15:58:41 jwf: Karma for langdon changed to 4 (for the f27 release cycle): https://badges.fedoraproject.org/tags/cookie/any 15:58:44 jwf: Karma for asamalik changed to 2 (for the f27 release cycle): https://badges.fedoraproject.org/tags/cookie/any 15:58:46 mayorga: That would be super cool 15:58:56 mayorga: From my POV, I think it's a valuable use of time 15:59:10 I would love to share that people even for things like Community Blog and Fedora Magazine, in addition to docs 16:04:14 \o/ 16:04:40 sumantro_|dinner: see https://pagure.io/fedora-docs/quick-docs/blob/master/f/en-US/3rdparty-message.adoc 16:11:57 asamalik[m]: do you want to come over here and talk about the plan for the modularity docs? 16:17:04 langdon: sure 16:22:53 langdon: https://redhat-documentation.github.io/modular-docs/ 16:25:10 If you are working in a wiki transformed/translated/migrated document, take into account that inline monospaced text is wiped out in the translation 16:50:15 zoglesby, we miss you! 16:50:28 bstinson, thank you - will try to read and have it digested for your AM tomorrow 17:30:08 Whooo, first PR \o/ 17:30:09 https://pagure.io/fedora-commops/pull-request/139 17:30:19 If any veterans want to take a look here, I'd appreciate it ^^ 17:30:29 I'm going to be packing up soon, so a Pagure ticket comment is best if you take a look 17:40:45 sumantro_ and other remotees - we are going to break up - sorry for losing video connection while I had to take a meeting 18:07:04 And one last one: 18:07:07 https://pagure.io/fedora-commops/pull-request/140 18:07:19 Anyone that wants to review that one, feedback is welcome 18:07:27 Otherwise, I think we are definitely packing up now. 18:07:33 So I'm going to close out the meeting and send minutes to the list! 18:07:40 Thanks for hanging out with us today, everyone \o/ 18:07:42 #endmeeting