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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
