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)
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)
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)
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)
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)
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)
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)
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)