I'm looking for somewhere to get started on the wiki, and I'm not sure where to proceed?
This lead me to the Drafts wiki page, am I free to edit these pages as I see fit? What is the etiquette here?
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. 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.
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. 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".
Just some thoughts...
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
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.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
I will start translating the DUG to spanish (neutral, LATAM style). Any recommendations / tips / is there anyone doing it?
Y.S. nc
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
BTW: Can anyone copy /Docs/Drafts/DesktopuserGuide to NicolasCorrarello/DesktopUserGuide so I can work it there? Nicolas Antonio Corrarello escribió:
I will start translating the DUG to spanish (neutral, LATAM style). Any recommendations / tips / is there anyone doing it?
Y.S. nc
On Mon, 2007-04-30 at 13:52 -0400, Paul W. Frields wrote:
On Mon, 2007-04-30 at 08:47 -0700, Karsten Wade wrote:
Fortunately, we also have a Style Guide which documents grammar, usage, etc. for use in the official docs:
Yes, but it doesn't cover voice[1]. We could set an overall voice that is a little different from e.g. traditional corporate technical content. Here are some that I could see us adopting:
* Jokey (light-hearted) * Casual (mildly jokey, addition of more pronouns) * Metal ("This guide teaches you how to *brutalize* your Fedora install...")
[1] Voice is the tone that writing takes. It is the overall tone (sarcastic, excited, didactic, bored, informative, etc.). It is also the individual character, which usually comes from a single writer (Neil Gaiman's voice is different from Stephen King's, Neal Stephenson's, and H.L. Mencken's.)
And don't forget that we can also update our Jargon Buster with these terms, including a citation to Wikipedia, et al.
Are we comfortable with setting a requirement for inclusion in the Fedora Glossary (was Jargon Buster)? Such as, "Include the term if the term has a special meaning in Fedora that is different or in addition to a meaning found in an upstream dictionary/glossary." For example, "yum repo" and "yum repository" could use a canonical definition.
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.
Sure, StyleGuide.
Maybe we'll eventually pick the Documentation Guide of all the meat and bury the carcass?
It's not that the content isn't relevant, it's that it has found its way into more relevant or actively maintained places.
Anyway ...
- Karsten
On Wed, 2007-05-02 at 16:16 -0700, Karsten Wade wrote:
On Mon, 2007-04-30 at 13:52 -0400, Paul W. Frields wrote:
On Mon, 2007-04-30 at 08:47 -0700, Karsten Wade wrote:
Fortunately, we also have a Style Guide which documents grammar, usage, etc. for use in the official docs:
Yes, but it doesn't cover voice[1]. We could set an overall voice that is a little different from e.g. traditional corporate technical content. Here are some that I could see us adopting:
- Jokey (light-hearted)
- Casual (mildly jokey, addition of more pronouns)
- Metal ("This guide teaches you how to *brutalize* your Fedora
install...")
[1] Voice is the tone that writing takes. It is the overall tone (sarcastic, excited, didactic, bored, informative, etc.). It is also the individual character, which usually comes from a single writer (Neil Gaiman's voice is different from Stephen King's, Neal Stephenson's, and H.L. Mencken's.)
I know which one I'm going to use... BESERKER!!! ;-D
And don't forget that we can also update our Jargon Buster with these terms, including a citation to Wikipedia, et al.
Are we comfortable with setting a requirement for inclusion in the Fedora Glossary (was Jargon Buster)? Such as, "Include the term if the term has a special meaning in Fedora that is different or in addition to a meaning found in an upstream dictionary/glossary." For example, "yum repo" and "yum repository" could use a canonical definition.
+1.
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.
Sure, StyleGuide.
Maybe we'll eventually pick the Documentation Guide of all the meat and bury the carcass?
It's not that the content isn't relevant, it's that it has found its way into more relevant or actively maintained places.
I think the main problem is that our toolchain is like much of Fedora development, and changes faster than the docs can keep up. Since this particular doc is more or less *about* those tools, built *by* those tools, it's exponentially harder to keep updated.
This may get easier in a XHTML <-> DocBook/XML Plone-y world... In the meantime, sure, cutting this down to size would be good. I've done a big update in the module structure area, but it probably needs new work since there are changes made in just the last 30 days that affect it. See, there you go...
docs@lists.stg.fedoraproject.org
-
Francis Earl -
Karsten Wade -
Nicolas A. Corrarello -
Paul W. Frields