[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: Wiki starting points? Drafts...

On Mon, 2007-04-30 at 08:47 -0700, Karsten Wade wrote:
> On Sun, 2007-04-29 at 14:22 -0700, Francis Earl wrote:
> > Just looking briefly at the "Getting Started" page, I believe a few
> > improvements could be made. It's overtone is very professional, which is
> > intimidating. 
> In absence of a good, fixed voice for Fedora Docs, we default to the
> traditional tech writing mode.  Setting a new tone is a good idea, but a
> lot more work than you may realize.  If you rewrite it to sound like
> you, then you have to work up a set of rules that others can follow to
> make sure they can write in a similar style.
> What happens in a Wiki is that people write in their personal style, and
> in trying to wrangle them all all together, all personality is erased.
> It would be great if we had a set of "voice instructions" that we could
> use when writing and editing.  Something that is easy to use like this
> is:
> http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms

Fortunately, we also have a Style Guide which documents grammar, usage,
etc. for use in the official docs:


> > I also think things like Graphic User Interface and Window
> > Manager should provide links to wikipedia so the user can learn more
> > about the topic if they wish. Wikipedia is provided in the Free Content
> > bookmarks folder in Fedora 7t4, so I don't think that would be an issue?
> > I think the wiki is the wrong place to try and explain such things
> > though.
> Sure, good idea, we should save ourselves explaining things that don't
> matter.  We can't actually pull in Wikipedia content (wrong license),
> but we can link to them.

And don't forget that we can also update our Jargon Buster with these
terms, including a citation to Wikipedia, et al.

> > Also, I don't see a way to upload images? There is a saying "a picture
> > tells a thousand words", and I believe it's true. 
> Yes, but a screenshot is not a picture.  It is mainly a bunch of pixels
> that have no meaning (>80%) and a few pixels that do have meaning.  
> When an image is a diagram, it is useful.  A screenshot that is
> converted into a diagram is useful.  However, it has to be worth the
> extra hassle to translated.
> SVG files give us a pathway to translation.  Raster graphics
> (screenshots) require all translators to perfectly recreate the graphic
> in their native language.  GUIs often change right up to the end, so
> *every single screenshot* has to be double-checked for accuracy just
> before release, then any fixed, and all translators have to update their
> versions.  FWIW, I've seen this in action, and it's a PITA.
> For 90%+ of cases where a screenshot is used, a short piece of text can
> be used instead.  That is much easier to translate and correct when the
> GUI is changed.

And I can tell you, also, from several iterations of the Installation
Guide that the "we'll just get translators to reproduce it" model
doesn't work well.  I completely trust in their ability to do it, but
the amount of effort and time it takes simply puts it at a much lower
priority than doing string translations.  Thus, we use the guideline to
avoid screenshots whenever possible.

It's interesting that in printed books, I believe very much in visual
learning -- the Head First book series is an excellent example of how to
do this well.  That approach, however, requires *MAJOR* efforts in
layout and design that we can't reasonably reproduce with a wiki or
DocBook.  So instead, we go for the most effective and efficient
approach, which still conveys maximum information to the reader:  clear,
simple writing.

> > I don't even see a way
> > to add images though? Screenshots (of a particular section of relevance
> > on the desktop) would greatly clarify what things say, and provide an
> > air of confidence for the user "I must be doing it right, it looks the
> > same".
> For example, in the DUG, I think the screenshot slices of the desktop
> are quite useful.  This is because it is hard to describe something that
> is entirely graphical and can be customized to move around on the
> desktop.
> http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Tour
> Well, hmmm ... the part I liked there was removed, which showed the
> various toolbar/elements of the desktop along with an explanation of
> their usage.  The current version, which shows a full desktop and then
> explains around it, I find more confusing.
> Heh, heh ... now that this has come up on list a few times recently
> (refer to the archives for more of the same), maybe I need to write all
> this up at DocsProject/Screenshots. :)

How about in the Style Guide?  Currently this is in the Documentation
Guide, but if it doesn't fit we could yank it from there and link to it

Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]