#fedora-docs: Fedora Documentation FAD 2018 - Day 1

Meeting started by jwf at 08:57:06 UTC (full logs).

Meeting summary

  1. Work session (jwf, 08:57:26)
    1. https://pagure.io/fedora-docs-container (jwf, 08:58:06)

  2. Topics (jwf, 08:59:05)
    1. Conversation on git (jwf, 08:59:09)
    2. Introducing AsciiDoc (jwf, 08:59:20)
    3. Introducing AsciiBinder (jwf, 08:59:26)
    4. Workflow / repo structure (jwf, 09:00:04)
    5. Quick-docs vs. books (jwf, 09:00:15)
    6. Modular docs intro (?) (jwf, 09:00:45)

  3. Workflow / repo structure (jwf, 09:00:55)
    1. https://pagure.io/fedora-docs (jwf, 09:01:24)
    2. This is mostly a reference repo; used so we can complete that URL (jwf, 09:01:38)
    3. https://pagure.io/fedora-docs/docs-fp-o (jwf, 09:01:47)
    4. docs-fp-o is master docs repo (jwf, 09:01:58)
    5. All CSS and other content (ryanlerch helping with this) (jwf, 09:02:14)
    6. Builder script that actually builds all the docs (jwf, 09:02:25)
    7. Old book format: en-US (jwf, 09:02:37)
    8. _topic-map.yml is where you list all things that actually should be published (jwf, 09:02:54)
    9. Fedora Release Notes > Book Information > Welcome to Fedora (jwf, 09:04:15)
    10. https://pagure.io/fedora-docs/release-notes/blob/master/f/_topic_map.yml (jwf, 09:04:53)
    11. https://docs.fedoraproject.org/f27/release-notes/index.html (jwf, 09:05:56)
    12. File name doesn't have to match menu name (jwf, 09:06:03)
    13. Test changes locally for any content repo (i.e. a repo that holds AsciiDoc pages, not the whole shebang) (jwf, 09:09:07)
    14. Builds piece of the docs locally, not EVERYTHING (jwf, 09:09:19)
    15. IDEA: Focus on content – things like CSS may be out of sync in content repos. Don't worry about it. Focus on content. (jwf, 09:09:50)
    16. === Branching === (jwf, 09:10:30)
    17. Think about the work you're doing and the context of the latest version of Fedora (jwf, 09:10:41)
    18. Less value in fixing something in f26 vs. f28 (jwf, 09:10:48)
    19. Every repo has master branch – represents Rawhide (jwf, 09:10:58)
    20. IDEA: Represents latest version of the docs and what we want to ship (jwf, 09:11:08)
    21. ACTION: docs-writers Target working on master branch / latest version as much as possible (jwf, 09:11:39)
    22. Some repos will only ever have a master branch (Council docs, CommOps docs, etc.) (jwf, 09:15:41)

  4. Issues (jwf, 09:18:02)
    1. File issues / tickets for content in the individual repos (jwf, 09:18:14)
    2. Builder issues / tickets go to builder repo (docs-fp-o) (jwf, 09:18:24)
    3. IDEA: Community repo for tickets / issues: Not considered yet, but will revisit? (jwf, 09:21:50)
    4. HELP: People still file bugs in Bugzilla… need to work on publicity for that (jwf, 09:23:08)

  5. Problems we have today (jwf, 09:24:21)
    1. Creating internal links (jwf, 09:24:31)
    2. Images must be in images subdirectory to render (jwf, 09:25:00)
    3. ACTION: docs-writers Use smaller images whenever possible – AsciiBinder base64's images and renders them in HTML. Images should be small. (fixed someday??) (jwf, 09:26:56)

  6. Style guide (jwf, 09:28:16)
    1. Something we don't have but want to work on (jwf, 09:28:21)
    2. ACTION: docs-writers Please use ATX style for now (i.e. headers preceded by equal signs instead of underlining text) (jwf, 09:28:42)
    3. ACTION: docs-writers One sentence per line (makes diffs look REALLY nice, but weird to read) (jwf, 09:29:14)
    4. 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. (jwf, 09:30:06)
    5. ACTION: docs-writers Use small images when possible (see caveat above) (jwf, 09:30:41)
    6. HELP: If you need help or have questions on styling, please ask when they come up. Remotees can ask in this channel during FAD. (jwf, 09:31:15)

  7. Modular docs (preview) - rkratky (jwf, 09:32:31)
    1. Potential in quick-docs for modular docs: individual things people want to do in Fedora (jwf, 09:32:49)
    2. Modularization: Common, repeating text across files (intro, installing RPMs, other generic info); write once and <include> over and over (jwf, 09:33:18)
    3. IDEA: Think of docs modularity as word recycling or duplicating blocks of code (jwf, 09:33:48)
    4. rkratky to give intro on how to do this later on in FAD… stay tuned! (jwf, 09:34:06)

  8. Entities - bexelbie (jwf, 09:36:13)
    1. https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/en-US/entities.adoc (jwf, 09:37:49)
    2. IDEA: Entities are variables you can reuse across docs (jwf, 09:38:33)
    3. https://pagure.io/fedora-docs-container a handy command to do asciibinding within a docker container (langdon, 09:39:12)
    4. https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/en-US/basic-system-configuration/Configuring_the_Date_and_Time.adoc#_3 (jwf, 09:40:24)

  9. Break (jwf, 09:48:31)
  10. Introduction to AsciiDoc (jwf, 10:04:44)
    1. AsciiDoc: Lightweight markup language, a helpful quick reference page online (jwf, 10:05:46)
    2. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ (jwf, 10:05:53)
    3. Whitespace matters (e.g. list items must be separated by whitespace) (jwf, 10:07:15)
    4. Lets you create various types of docs - we use it for books (jwf, 10:07:24)
    5. Also works for man pages, articles, etc. (jwf, 10:07:32)
    6. === How it's built === (jwf, 10:07:44)
    7. AsciiDoctor most commonly used to build it (jwf, 10:07:50)
    8. We have a AsciiDocTutorial repo but it's currently internal – will make public during FAD (jwf, 10:10:12)
    9. H1 value is a title of book / doc – only one H1 value per ADoc (jwf, 10:11:11)
    10. Use Unicode characters (jwf, 10:12:14)
    11. Q: Square brackets at end of include directive? [] (jwf, 10:13:29)
    12. A: Square brackets often used. For include directive, you can make config changes (e.g. `leveloffset=+1`) (jwf, 10:14:22)
    13. 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. (jwf, 10:15:20)
    14. 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. (jwf, 10:18:39)
    15. === Basic markup === (jwf, 10:19:56)
    16. Most of the "basics" are online in the quick reference (jwf, 10:20:18)
    17. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ (jwf, 10:20:23)
    18. ACTION: docs-writers Be consistent! Whatever you do for styling, be consistent with what you use (jwf, 10:24:55)
    19. AsciiDoc has a limit of five levels for ordered lists (jwf, 10:27:00)
    20. Create ordered lists with periods (nifty – if you've used other markup languages, this is a simple and effective way for ordered lists) (jwf, 10:28:23)
    21. Checklists are also natively supported. We don't use them often in Fedora Docs proper, may be useful for some sub-projects (jwf, 10:30:44)
    22. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#horizontal-rules-and-page-breaks (jwf, 10:30:48)
    23. Labeled lists do not go into the table of contents (jwf, 10:31:06)
    24. Q&A section also natively supported!! (jwf, 10:33:15)
    25. AsciiBinder uses AsciiDoctor to render AsciiDoc (jwf, 10:33:36)
    26. 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 (jwf, 10:34:26)
    27. Literal blocks support syntax highlighting with a line above them, e.g. [source,bash] (jwf, 10:39:18)
    28. Literal blocks can also inherit entities (e.g. [source,bash,subs="attributes+"]), but you have to explicitly call them (otherwise, it renders as plaintext) (jwf, 10:40:46)
    29. Paragraphs: Whitespace between paragraphs required; whitespace between headers and body text encouraged (jwf, 10:47:09)
    30. + signs are a way to render soft returns in the text; must be placed at end of line in source doc (jwf, 10:50:22)
    31. === Tables === (jwf, 10:50:51)
    32. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables (jwf, 10:52:40)
    33. jwf is super-enthused about how pretty the tables are (mattdm, 10:53:51)
    34. But beware translation woes: Tables are hard to translate and different languages order text differently (jwf, 10:54:23)
    35. IDEA: Complex tables will (likely) never be translated (jwf, 10:54:35)
    36. Think of the information you are presenting and what is the best way to present that (jwf, 10:58:10)
    37. Docs philosophy wisdom from bexelbie: "If you are using four sublevels of bullets or tables, you may be presenting the info wrong." (jwf, 10:58:56)
    38. 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 (jwf, 10:59:38)
    39. remember almost no manpages need a table :D (bexelbie, 11:02:42)
    40. === Admonition blocks === (jwf, 11:03:36)
    41. In English? Special blocks of text that get icons (e.g. an info icon, light bulb, FontAwesome icons in general) (jwf, 11:03:56)
    42. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#more-delimited-blocks (jwf, 11:04:14)
    43. https://valelint.github.io/docs/ (jwf, 11:18:25)
    44. https://budget.fedoraproject.org/budget/docs/faq_entries.html (bexelbie, 11:19:33)
    45. ACTION: bexelbie hey let's integrate valelint into the CI PR workflow (mattdm, 11:19:51)
    46. Callouts are a handy way to annotate literal blocks: see quick reference docs for details on how to do this (jwf, 11:23:45)

  11. Lunch break (jwf, 13:19:52)
  12. Hack Time! (jwf, 13:26:48)
    1. 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 (jwf, 13:27:36)
    2. http://etherpad.osuosl.org/fdocs2018 (jwf, 13:44:12)
    3. How to SEO-magically redirect a wiki page into a docs page: {{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}} (jwf, 14:57:12)
    4. https://pagure.io/fedora-commops/pull-request/139 (jwf, 17:30:09)
    5. https://pagure.io/fedora-commops/pull-request/140 (jwf, 18:07:07)


Meeting ended at 18:07:42 UTC (full logs).

Action items

  1. docs-writers Target working on master branch / latest version as much as possible
  2. docs-writers Use smaller images whenever possible – AsciiBinder base64's images and renders them in HTML. Images should be small. (fixed someday??)
  3. docs-writers Please use ATX style for now (i.e. headers preceded by equal signs instead of underlining text)
  4. docs-writers One sentence per line (makes diffs look REALLY nice, but weird to read)
  5. docs-writers Use small images when possible (see caveat above)
  6. docs-writers Be consistent! Whatever you do for styling, be consistent with what you use
  7. bexelbie hey let's integrate valelint into the CI PR workflow


Action items, by person

  1. bexelbie
    1. bexelbie hey let's integrate valelint into the CI PR workflow
  2. docs-writers
    1. docs-writers Target working on master branch / latest version as much as possible
    2. docs-writers Use smaller images whenever possible – AsciiBinder base64's images and renders them in HTML. Images should be small. (fixed someday??)
    3. docs-writers Please use ATX style for now (i.e. headers preceded by equal signs instead of underlining text)
    4. docs-writers One sentence per line (makes diffs look REALLY nice, but weird to read)
    5. docs-writers Use small images when possible (see caveat above)
    6. docs-writers Be consistent! Whatever you do for styling, be consistent with what you use


People present (lines said)

  1. jwf (228)
  2. zodbot (24)
  3. bexelbie (17)
  4. langdon (11)
  5. mattdm (10)
  6. asamalik[m] (9)
  7. sumantro_ (9)
  8. pbokoc (6)
  9. mayorga (2)
  10. cverna (1)
  11. bstinson (1)
  12. zoglesby (1)
  13. x3mboy (1)
  14. ryanlerch (0)
  15. rkratky (0)
  16. docs-writers (0)
  17. Srijita (0)
  18. coremodule (0)
  19. jsmith (0)


Generated by MeetBot 0.1.4.