Wiki starting points? Drafts...

[Paul W. Frields]

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:

http://fedoraproject.org/wiki/DocsProject/StyleGuide 


> > 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
instead.

-- 
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070430/2675bc92/attachment.sig>