Wiki starting points? Drafts...

[Karsten Wade]

On Sun, 2007-04-29 at 14:22 -0700, Francis Earl wrote:
> I'm looking for somewhere to get started on the wiki, and I'm not sure
> where to proceed?

At this point, moving rapidly toward the F7 release, we need help on the
Wiki in these documents:

http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide
http://fedoraproject.org/wiki/Docs/Drafts/SoftwareManagementGuide

> This lead me to the Drafts wiki page, am I free to edit these pages as I
> see fit? What is the etiquette here?

Essentially, yes.  Writers for individual guides are watching those
guides, and some of us watch all changes.

I recommend that you make short changes and save often.  That way, if
you start down a path and could use some course correction, we can catch
it before you get too far along the path. :)

> 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

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

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

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

- Karsten
-- 
   Karsten Wade, 108 Editor       ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- 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/eb6c37f5/attachment.sig>