3:22 p.m.
I decided we needed a good, standard way within our wiki documentation
to say to "do this, but don't do this". I have produced a template to
assist with that.
https://fedoraproject.org/wiki/Template:Do_this_not_this
It's includable on a page like so:
{{do this not this|do=You should do this|dont=But not this|why=Because I
said so}}
Feedback? Is there a way that DocBook does it? Am I forgetting something
major?
--
Ian Weller <ianweller(a)gmail.com> http://ianweller.org
GnuPG fingerprint: E51E 0517 7A92 70A2 4226 B050 87ED 7C97 EFA8 4A36
"Technology is a word that describes something that doesn't work yet."
~ Douglas Adams
1:34 p.m.
On Sun, 2008-09-21 at 15:22 -0500, Ian Weller wrote:
I decided we needed a good, standard way within our wiki
documentation
to say to "do this, but don't do this". I have produced a template to
assist with that.
https://fedoraproject.org/wiki/Template:Do_this_not_this
It's includable on a page like so:
{{do this not this|do=You should do this|dont=But not this|why=Because I
said so}}
Feedback? Is there a way that DocBook does it? Am I forgetting something
major?
There isn't a DocBook equivalent, so using this in this way would only
work on the wiki. We could find a way to map it to a DocBook setup,
which would likely be a table with "Do this" and "Do not do this"
column
headers. Or something.
As a wiki idea, I dig the concept. We want to consider how people
should use it in practice so there is not e.g. a long set of rows of
these making it hard to read the text.
The thing is, making them stand out as an admonition means we want to
use it more sparingly. Overuse causes eye abuse. :)
Another thing we could do is create a standard set of tables, such as a
"do/do not" table, and make them available from Help:Wiki_editing. It
doesn't let us control them centrally, but it at least helps us set and
evolve some consistency.
What is a good way to track usage of these tables so we can find and
update there usage when we update the templates?
- Karsten
--
Karsten Wade, Sr. Community Relations Guy
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41
5:30 p.m.
On Tue, Sep 23, 2008 at 11:34:02AM -0700, Karsten 'quaid' Wade wrote:
Another thing we could do is create a standard set of tables, such as
a
"do/do not" table, and make them available from Help:Wiki_editing. It
doesn't let us control them centrally, but it at least helps us set and
evolve some consistency.
What is a good way to track usage of these tables so we can find and
update there usage when we update the templates?
The best way to do this is make a template, and set up the variables
right the first time. Then it automatically changes when you change it,
of course. It's /much/ more difficult to just change syntax across an
entire set of pages.
I'm wondering if the template does need to be toned down a bit (perhaps
lose the colored backgrounds?) so that repetition (which I know will
happen) is not denounced.
--
Ian Weller <ianweller(a)gmail.com> http://ianweller.org
GnuPG fingerprint: E51E 0517 7A92 70A2 4226 B050 87ED 7C97 EFA8 4A36
"Technology is a word that describes something that doesn't work yet."
~ Douglas Adams
8:33 p.m.
On Wed, Sep 24, 2008 at 4:34 AM, Karsten 'quaid' Wade <kwade(a)redhat.com>
wrote:
[snip]
There isn't a DocBook equivalent, so using this in this way would
only
work on the wiki. We could find a way to map it to a DocBook setup,
which would likely be a table with "Do this" and "Do not do this"
column
headers. Or something.
Do not use a table if you only have two columns - use
<segmentedlist>[0] for this.
Cheers.
[0] <http://www.docbook.org/tdg/en/html/segmentedlist.html>
8:37 p.m.
Thank you to Chris Curran for providing this information.
Do not use a table if you only have two columns - use
<segmentedlist>[0] for this.
Cheers.
[0] <http://www.docbook.org/tdg/en/html/segmentedlist.html>
9:51 a.m.
On Wed, 2008-09-24 at 11:37 +1000, Murray McAllister wrote:
Thank you to Chris Curran for providing this information.
> Do not use a table if you only have two columns - use
> <segmentedlist>[0] for this.
>
> Cheers.
>
> [0] <http://www.docbook.org/tdg/en/html/segmentedlist.html>
I like to use segmentedlist elements even in cases where there are
*more* than two columns. A segmentedlist, in true DocBook spirit,
separates the format from the meaning. It can be rendered in different
formats (tabular versus labeled list entries) that make more sense to
blind readers too.
--
Paul W. Frields
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://paul.frields.org/ - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
11:22 a.m.
On Wed, 2008-09-24 at 11:33 +1000, Murray McAllister wrote:
On Wed, Sep 24, 2008 at 4:34 AM, Karsten 'quaid' Wade
<kwade(a)redhat.com> wrote:
[snip]
> There isn't a DocBook equivalent, so using this in this way would only
> work on the wiki. We could find a way to map it to a DocBook setup,
> which would likely be a table with "Do this" and "Do not do
this" column
> headers. Or something.
Do not use a table if you only have two columns - use
<segmentedlist>[0] for this.
Makes sense, we could map {{do this not this}} to a segmentedlist.
- Karsten
--
Karsten Wade, Community Gardener
Dev Fu : http://developer.redhatmagazine.com
Fedora : http://quaid.fedorapeople.org
gpg key : AD0E0C41
6:48 p.m.
On Wed, Sep 24, 2008 at 09:22:43AM -0700, Karsten 'quaid' Wade wrote:
Makes sense, we could map {{do this not this}} to a segmentedlist.
Please edit or suggest edits as necessary :)
I don't think the admonition is in use anywhere yet.
[[Special:Whatlinkshere]] would tell you for sure, though.
--
Ian Weller <ianweller(a)gmail.com> http://ianweller.org
GnuPG fingerprint: E51E 0517 7A92 70A2 4226 B050 87ED 7C97 EFA8 4A36
"Technology is a word that describes something that doesn't work yet."
~ Douglas Adams
5687
days inactive
5690
days old
7 comments
4 participants
participants (4)
-
Ian Weller -
Karsten Wade -
Murray McAllister -
Paul W. Frields