jwf's meeting titled "Fedora Documentation FAD 2018 - Day 1" ended in
#fedora-docs
by notifications@fedoraproject.org
===================================================
#fedora-docs: Fedora Documentation FAD 2018 - Day 1
===================================================
Meeting started by jwf at 08:57:06 UTC. The full logs are available at
https://meetbot.fedoraproject.org/fedora-docs/2018-02-26/fedora_docs.2018...
.
Meeting summary
---------------
* Work session (jwf, 08:57:26)
* LINK: https://pagure.io/fedora-docs-container (jwf, 08:58:06)
* Topics (jwf, 08:59:05)
* Conversation on git (jwf, 08:59:09)
* Introducing AsciiDoc (jwf, 08:59:20)
* Introducing AsciiBinder (jwf, 08:59:26)
* Workflow / repo structure (jwf, 09:00:04)
* Quick-docs vs. books (jwf, 09:00:15)
* Modular docs intro (?) (jwf, 09:00:45)
* Workflow / repo structure (jwf, 09:00:55)
* LINK: https://pagure.io/fedora-docs (jwf, 09:01:24)
* This is mostly a reference repo; used so we can complete that URL
(jwf, 09:01:38)
* LINK: https://pagure.io/fedora-docs/docs-fp-o (jwf, 09:01:47)
* docs-fp-o is master docs repo (jwf, 09:01:58)
* All CSS and other content (ryanlerch helping with this) (jwf,
09:02:14)
* Builder script that actually builds all the docs (jwf, 09:02:25)
* Old book format: en-US (jwf, 09:02:37)
* _topic-map.yml is where you list all things that actually should be
published (jwf, 09:02:54)
* Fedora Release Notes > Book Information > Welcome to Fedora (jwf,
09:04:15)
* LINK:
https://pagure.io/fedora-docs/release-notes/blob/master/f/_topic_map.yml
(jwf, 09:04:53)
* LINK: https://docs.fedoraproject.org/f27/release-notes/index.html
(jwf, 09:05:56)
* File name doesn't have to match menu name (jwf, 09:06:03)
* Test changes locally for any content repo (i.e. a repo that holds
AsciiDoc pages, not the whole shebang) (jwf, 09:09:07)
* Builds piece of the docs locally, not EVERYTHING (jwf, 09:09:19)
* 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)
* === Branching === (jwf, 09:10:30)
* Think about the work you're doing and the context of the latest
version of Fedora (jwf, 09:10:41)
* Less value in fixing something in f26 vs. f28 (jwf, 09:10:48)
* Every repo has master branch – represents Rawhide (jwf, 09:10:58)
* IDEA: Represents latest version of the docs and what we want to ship
(jwf, 09:11:08)
* ACTION: docs-writers Target working on master branch / latest
version as much as possible (jwf, 09:11:39)
* Some repos will only ever have a master branch (Council docs,
CommOps docs, etc.) (jwf, 09:15:41)
* Issues (jwf, 09:18:02)
* File issues / tickets for content in the individual repos (jwf,
09:18:14)
* Builder issues / tickets go to builder repo (docs-fp-o) (jwf,
09:18:24)
* IDEA: Community repo for tickets / issues: Not considered yet, but
will revisit? (jwf, 09:21:50)
* HELP: People still file bugs in Bugzilla… need to work on publicity
for that (jwf, 09:23:08)
* Problems we have today (jwf, 09:24:21)
* Creating internal links (jwf, 09:24:31)
* Images must be in images subdirectory to render (jwf, 09:25:00)
* 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)
* Style guide (jwf, 09:28:16)
* Something we don't have but want to work on (jwf, 09:28:21)
* ACTION: docs-writers Please use ATX style for now (i.e. headers
preceded by equal signs instead of underlining text) (jwf,
09:28:42)
* ACTION: docs-writers One sentence per line (makes diffs look REALLY
nice, but weird to read) (jwf, 09:29:14)
* 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)
* ACTION: docs-writers Use small images when possible (see caveat
above) (jwf, 09:30:41)
* 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)
* Modular docs (preview) - rkratky (jwf, 09:32:31)
* Potential in quick-docs for modular docs: individual things people
want to do in Fedora (jwf, 09:32:49)
* Modularization: Common, repeating text across files (intro,
installing RPMs, other generic info); write once and <include> over
and over (jwf, 09:33:18)
* IDEA: Think of docs modularity as word recycling or duplicating
blocks of code (jwf, 09:33:48)
* rkratky to give intro on how to do this later on in FAD… stay tuned!
(jwf, 09:34:06)
* Entities - bexelbie (jwf, 09:36:13)
* LINK:
https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/e...
(jwf, 09:37:49)
* IDEA: Entities are variables you can reuse across docs (jwf,
09:38:33)
* LINK: https://pagure.io/fedora-docs-container a handy command to do
asciibinding within a docker container (langdon, 09:39:12)
* LINK:
https://pagure.io/fedora-docs/system-administrators-guide/blob/master/f/e...
(jwf, 09:40:24)
* Break (jwf, 09:48:31)
* Introduction to AsciiDoc (jwf, 10:04:44)
* AsciiDoc: Lightweight markup language, a helpful quick reference
page online (jwf, 10:05:46)
* LINK: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
(jwf, 10:05:53)
* Whitespace matters (e.g. list items must be separated by whitespace)
(jwf, 10:07:15)
* Lets you create various types of docs - we use it for books (jwf,
10:07:24)
* Also works for man pages, articles, etc. (jwf, 10:07:32)
* === How it's built === (jwf, 10:07:44)
* AsciiDoctor most commonly used to build it (jwf, 10:07:50)
* We have a AsciiDocTutorial repo but it's currently internal – will
make public during FAD (jwf, 10:10:12)
* H1 value is a title of book / doc – only one H1 value per ADoc
(jwf, 10:11:11)
* Use Unicode characters (jwf, 10:12:14)
* Q: Square brackets at end of include directive? [] (jwf, 10:13:29)
* A: Square brackets often used. For include directive, you can make
config changes (e.g. `leveloffset=+1`) (jwf, 10:14:22)
* 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)
* 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)
* === Basic markup === (jwf, 10:19:56)
* Most of the "basics" are online in the quick reference (jwf,
10:20:18)
* LINK: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
(jwf, 10:20:23)
* ACTION: docs-writers Be consistent! Whatever you do for styling, be
consistent with what you use (jwf, 10:24:55)
* AsciiDoc has a limit of five levels for ordered lists (jwf,
10:27:00)
* 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)
* 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)
* LINK:
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#horizontal-...
(jwf, 10:30:48)
* Labeled lists do not go into the table of contents (jwf, 10:31:06)
* Q&A section also natively supported!! (jwf, 10:33:15)
* AsciiBinder uses AsciiDoctor to render AsciiDoc (jwf, 10:33:36)
* 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)
* Literal blocks support syntax highlighting with a line above them,
e.g. [source,bash] (jwf, 10:39:18)
* 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)
* Paragraphs: Whitespace between paragraphs required; whitespace
between headers and body text encouraged (jwf, 10:47:09)
* + 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)
* === Tables === (jwf, 10:50:51)
* LINK:
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables
(jwf, 10:52:40)
* jwf is super-enthused about how pretty the tables are (mattdm,
10:53:51)
* But beware translation woes: Tables are hard to translate and
different languages order text differently (jwf, 10:54:23)
* IDEA: Complex tables will (likely) never be translated (jwf,
10:54:35)
* Think of the information you are presenting and what is the best way
to present that (jwf, 10:58:10)
* 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)
* 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)
* remember almost no manpages need a table :D (bexelbie, 11:02:42)
* === Admonition blocks === (jwf, 11:03:36)
* In English? Special blocks of text that get icons (e.g. an info
icon, light bulb, FontAwesome icons in general) (jwf, 11:03:56)
* LINK:
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#more-delimi...
(jwf, 11:04:14)
* LINK: https://valelint.github.io/docs/ (jwf, 11:18:25)
* LINK: https://budget.fedoraproject.org/budget/docs/faq_entries.html
(bexelbie, 11:19:33)
* ACTION: bexelbie hey let's integrate valelint into the CI PR
workflow (mattdm, 11:19:51)
* Callouts are a handy way to annotate literal blocks: see quick
reference docs for details on how to do this (jwf, 11:23:45)
* Lunch break (jwf, 13:19:52)
* Hack Time! (jwf, 13:26:48)
* 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)
* LINK: http://etherpad.osuosl.org/fdocs2018 (jwf, 13:44:12)
* 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)
* LINK: https://pagure.io/fedora-commops/pull-request/139 (jwf,
17:30:09)
* LINK: https://pagure.io/fedora-commops/pull-request/140 (jwf,
18:07:07)
Meeting ended at 18:07:42 UTC.
Action Items
------------
* docs-writers Target working on master branch / latest version as much
as possible
* docs-writers Use smaller images whenever possible – AsciiBinder
base64's images and renders them in HTML. Images should be small.
(fixed someday??)
* docs-writers Please use ATX style for now (i.e. headers preceded by
equal signs instead of underlining text)
* docs-writers One sentence per line (makes diffs look REALLY nice, but
weird to read)
* docs-writers Use small images when possible (see caveat above)
* docs-writers Be consistent! Whatever you do for styling, be consistent
with what you use
* bexelbie hey let's integrate valelint into the CI PR workflow
Action Items, by person
-----------------------
* bexelbie
* bexelbie hey let's integrate valelint into the CI PR workflow
* docs-writers
* docs-writers Target working on master branch / latest version as
much as possible
* docs-writers Use smaller images whenever possible – AsciiBinder
base64's images and renders them in HTML. Images should be small.
(fixed someday??)
* docs-writers Please use ATX style for now (i.e. headers preceded by
equal signs instead of underlining text)
* docs-writers One sentence per line (makes diffs look REALLY nice,
but weird to read)
* docs-writers Use small images when possible (see caveat above)
* docs-writers Be consistent! Whatever you do for styling, be
consistent with what you use
* **UNASSIGNED**
* (none)
People Present (lines said)
---------------------------
* jwf (228)
* zodbot (24)
* bexelbie (17)
* langdon (11)
* mattdm (10)
* asamalik[m] (9)
* sumantro_ (9)
* pbokoc (6)
* mayorga (2)
* cverna (1)
* bstinson (1)
* zoglesby (1)
* x3mboy (1)
* ryanlerch (0)
* rkratky (0)
* docs-writers (0)
* Srijita (0)
* coremodule (0)
* jsmith (0)
Generated by `MeetBot`_ 0.1.4
.. _`MeetBot`: http://wiki.debian.org/MeetBot
https://meetbot.fedoraproject.org/fedora-docs/2018-02-26/fedora_docs.2018...
--
You received this message due to your preference settings at
https://apps.fedoraproject.org/notifications/fmnmeetingminutes.id.fedorap...