I meant to reply to this thread but didn't get a chance when it was fresh. Now it is old and smelly, but we still love it just the same. :-) Let's get this one on the road. I would like to put the Style Guide to the side (not the same as on the back burner) while we work on this. The Style Guide is a great thing and necessary, but not as important as having an Installation Guide.
I think handing out chapter assignments (or alternately, taking volunteers for chapters) would give everyone an idea of authoring skill levels. It would also mean we could put the process doc to the test, and beyond that, give us good ideas to address in the Style Guide.
I was wondering about this - I couldn't find details on the tracking bug or the list archives.
I'd be interested in helping, if volunteers are needed. Looking at the TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable systems), but could probably tackle any of the other parts as required.
Now away until Monday, can pick up from there. -- Stuart Ellis s.ellis@fastmail.co.uk
On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote:
I meant to reply to this thread but didn't get a chance when it was fresh. Now it is old and smelly, but we still love it just the same. :-) Let's get this one on the road. I would like to put the Style Guide to the side (not the same as on the back burner) while we work on this. The Style Guide is a great thing and necessary, but not as important as having an Installation Guide.
I think handing out chapter assignments (or alternately, taking volunteers for chapters) would give everyone an idea of authoring skill levels. It would also mean we could put the process doc to the test, and beyond that, give us good ideas to address in the Style Guide.
I was wondering about this - I couldn't find details on the tracking bug or the list archives.
I'd be interested in helping, if volunteers are needed. Looking at the TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable systems), but could probably tackle any of the other parts as required.
Now away until Monday, can pick up from there.
Stuart Ellis
s.ellis@fastmail.co.uk
Glad you want to help with this. The first step is to create a ToC. If you want to create one and propose it to this list, that would be a wonderful start.
Tammy
On Fri, 2004-08-27 at 16:44, Tammy Fox wrote:
On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote:
I meant to reply to this thread but didn't get a chance when it was fresh. Now it is old and smelly, but we still love it just the same. :-) Let's get this one on the road. I would like to put the Style Guide to the side (not the same as on the back burner) while we work on this. The Style Guide is a great thing and necessary, but not as important as having an Installation Guide.
I think handing out chapter assignments (or alternately, taking volunteers for chapters) would give everyone an idea of authoring skill levels. It would also mean we could put the process doc to the test, and beyond that, give us good ideas to address in the Style Guide.
I was wondering about this - I couldn't find details on the tracking bug or the list archives.
I'd be interested in helping, if volunteers are needed. Looking at the TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable systems), but could probably tackle any of the other parts as required.
Now away until Monday, can pick up from there.
Glad you want to help with this. The first step is to create a ToC. If you want to create one and propose it to this list, that would be a wonderful start.
Tammy, I believe there's currently a ToC in CVS, as install-guide/fedora-install-guide-en-outline.txt -- could we use this?
On Fri, 2004-08-27 at 17:10, Paul W. Frields wrote:
On Fri, 2004-08-27 at 16:44, Tammy Fox wrote:
On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote:
I meant to reply to this thread but didn't get a chance when it was fresh. Now it is old and smelly, but we still love it just the same. :-) Let's get this one on the road. I would like to put the Style Guide to the side (not the same as on the back burner) while we work on this. The Style Guide is a great thing and necessary, but not as important as having an Installation Guide.
I think handing out chapter assignments (or alternately, taking volunteers for chapters) would give everyone an idea of authoring skill levels. It would also mean we could put the process doc to the test, and beyond that, give us good ideas to address in the Style Guide.
I was wondering about this - I couldn't find details on the tracking bug or the list archives.
I'd be interested in helping, if volunteers are needed. Looking at the TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable systems), but could probably tackle any of the other parts as required.
Now away until Monday, can pick up from there.
Glad you want to help with this. The first step is to create a ToC. If you want to create one and propose it to this list, that would be a wonderful start.
Tammy, I believe there's currently a ToC in CVS, as install-guide/fedora-install-guide-en-outline.txt -- could we use this? -- Paul W. Frields, RHCE
Oh yeah. I wrote that a long time ago and forgot about it. Thank goodness for CVS. ;-)
Tammy
Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911
I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I would like to suggest several guidelines for screenshots and any other graphics (I think the GDSG may use something similar to these, IIRC):
1. PNG format. Is that too obvious? 2. No wider than 500 pixels. If your graphic is larger than that, use GIMP (Image -> Scale Image) or mogrify to scale the image to no wider than 500 pixels. 3. Graphics should be included as <figure> I think.
Can someone else more knowledgeable in guide creation (*cough* Tammy *cough* Karsten *cough*) add to this list?
Here's another one I just thought of; the GDSG mentions this as well:
4. Graphics should not be included unless you absolutely *cannot* get along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?)
Okay, I'm onboard for the All Hands on Deck for an Installation Guide for FC3.
We have until about 20 October to have a release candidate, and this is possible to do if we make the pieces small enough and keep the editors busy.
More below ...
On Fri, 2004-08-27 at 15:33, Paul W. Frields wrote:
Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911
Below are some specific points, and I expanded on those suggestions in a patch to the Documentation Guide, as a new 7.3 Taking Screenshots. I'll reply back in a bit with the steps, after I build the DB and snarf them from the HTML page. :)
For expediency, I'm prepared to just submit the patch to the Doc Guide, rolling in some other dangling issues I can include. Tammy would see the CVS report and can address any mistakes and expand/modify.
I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I would like to suggest several guidelines for screenshots and any other graphics (I think the GDSG may use something similar to these, IIRC):
- PNG format. Is that too obvious?
And EPS.
- No wider than 500 pixels. If your graphic is larger than that, use
GIMP (Image -> Scale Image) or mogrify to scale the image to no wider than 500 pixels.
That seems reasonable. Make the GUI as small as it can to convey just what you need.
2.1 Use the default Metacity theme to give the guides a consistent look, and also consistent with most user's experience and expectations.
2.2 If you need to crop the image, do that in the GIMP to show just what you need.
- Graphics should be included as <figure> I think.
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure....
That shows the format. We kept the EPS first because of legacy jadetex issues, no idea if it matters anymore and I'm not tempting fate to find out. ;)
Here's another one I just thought of; the GDSG mentions this as well:
- Graphics should not be included unless you absolutely *cannot* get
along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?)
That seems reasonable. It's nice to have one screenshot to show the whole GUI, if that helps. It's probably better to have too few screenshots than too many.
For quality of information, I find <screen> blocks (as <example>s) with nice, useful command line output to be better ... :)
- Karsten
On Sat, 2004-08-28 at 00:33, Karsten Wade wrote:
Okay, I'm onboard for the All Hands on Deck for an Installation Guide for FC3.
We have until about 20 October to have a release candidate, and this is possible to do if we make the pieces small enough and keep the editors busy.
Is there any existing material we can use as a basis, or just guidance on how a Fedora doc should be ?
One of the nice things about working on GNOME docs is that between the Style Guide and the existing documentation the "house style" is very clearly defined, so that it was easy to write to the format. If nothing else is more appropriate, would the Release Notes be a good base-line in this respect ?
On Mon, 2004-08-30 at 13:20, Stuart Ellis wrote:
On Sat, 2004-08-28 at 00:33, Karsten Wade wrote:
Okay, I'm onboard for the All Hands on Deck for an Installation Guide for FC3.
We have until about 20 October to have a release candidate, and this is possible to do if we make the pieces small enough and keep the editors busy.
Is there any existing material we can use as a basis, or just guidance on how a Fedora doc should be ?
One of the nice things about working on GNOME docs is that between the Style Guide and the existing documentation the "house style" is very clearly defined, so that it was easy to write to the format. If nothing else is more appropriate, would the Release Notes be a good base-line in this respect ?
In the interest of speed, I think we're trying to make this up as we go on. To get docs out in time for FC3, we'll need to take an iterative approach:
1) Work with what we have. 2) Get caught by snags, resolve, propose the solution to the list. 3) With just a few +1s or -1s we resolve the matter and write it to the process/templates/Doc Guide/wherever that piece belongs. 4) Include the new style decisions, fix everything we have to match that, and move on. 5) Back to 1).
Still, we can take the next few days to hammer out more items, but much longer than that and we will be behind the curve.
I propose:
1) We make a short list of reference sites/materials. 2) When in doubt, refer to the list. 3) If two or more reference sites are contradictory, bring it to the mailing list. 4) Try to capture the definite items we want in our Style Guidelines - required sections, styles, etc. - as we go along
So far we can reference:
* Fedora Documentation Guide * GNOME Style Guide -- Paul had a recommended list of chapters * Red Hat documentation -- redhat.com/docs * Elements of Style -- free edition available
- Karsten
On Fri, 2004-08-27 at 19:33, Karsten Wade wrote:
Okay, I'm onboard for the All Hands on Deck for an Installation Guide for FC3.
We have until about 20 October to have a release candidate, and this is possible to do if we make the pieces small enough and keep the editors busy.
More below ...
On Fri, 2004-08-27 at 15:33, Paul W. Frields wrote:
Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911
Below are some specific points, and I expanded on those suggestions in a patch to the Documentation Guide, as a new 7.3 Taking Screenshots. I'll reply back in a bit with the steps, after I build the DB and snarf them from the HTML page. :)
For expediency, I'm prepared to just submit the patch to the Doc Guide, rolling in some other dangling issues I can include. Tammy would see the CVS report and can address any mistakes and expand/modify.
I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I would like to suggest several guidelines for screenshots and any other graphics (I think the GDSG may use something similar to these, IIRC):
- PNG format. Is that too obvious?
And EPS.
- No wider than 500 pixels. If your graphic is larger than that, use
GIMP (Image -> Scale Image) or mogrify to scale the image to no wider than 500 pixels.
That seems reasonable. Make the GUI as small as it can to convey just what you need.
2.1 Use the default Metacity theme to give the guides a consistent look, and also consistent with most user's experience and expectations.
2.2 If you need to crop the image, do that in the GIMP to show just what you need.
- Graphics should be included as <figure> I think.
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure....
That shows the format. We kept the EPS first because of legacy jadetex issues, no idea if it matters anymore and I'm not tempting fate to find out. ;)
Here's another one I just thought of; the GDSG mentions this as well:
- Graphics should not be included unless you absolutely *cannot* get
along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?)
I agree as long as we also keep the following in mind (from what I have learned working on the Red Hat IGs for 4 years and attending a usability study where newbies were given the IG and asked to install RHL for the first time):
1. Many people use the IG as a reference. When they get stuck, they refer to the Installation Guide and try to find help from that point forward. If this is the case, having a screenshot to match the one they are stuck on helps tremendously.
2. For people following the IG sequentially from the first screen forward, having a screenshot that looks like the one they are on helps confirm that they are proceeding correctly and makes them feel confident that they are performing the installation correctly.
3. Users find it useful to see sample data entered into the sample screenshot even if it is listed in the text. Some people just learn better visually.
That seems reasonable. It's nice to have one screenshot to show the whole GUI, if that helps. It's probably better to have too few screenshots than too many.
That being said, whoever is taking the screenshots should take them all and a few extra just in case we decide it is actually needed later. This will keep the size and sample data entered consistent throughout the screenshots.
Tammy
For quality of information, I find <screen> blocks (as <example>s) with nice, useful command line output to be better ... :)
- Karsten
-- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
On Mon, 2004-08-30 at 18:52, Tammy Fox wrote:
On Fri, 2004-08-27 at 19:33, Karsten Wade wrote:
Here's another one I just thought of; the GDSG mentions this as well:
- Graphics should not be included unless you absolutely *cannot* get
along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?)
I agree as long as we also keep the following in mind (from what I have learned working on the Red Hat IGs for 4 years and attending a usability study where newbies were given the IG and asked to install RHL for the first time):
This makes sense. The IG is a special creature -- the screens are sequential and don't have a bunch of pop-ups or menus to get lost in. For the IG, having at least one screenshot for each Anaconda page makes sense.
I think this "fewer screenshots is better" rule applies mainly to regular GUI applications. There is a style of how-to that has a screenshot for each piece of the GUI -- here's the drop down menu, here's the sub-menu, here's selecting the sub-menu, here's the window that comes up, here's the box checked, here's another box checked, etc.
- Many people use the IG as a reference. When they get stuck, they
refer to the Installation Guide and try to find help from that point forward. If this is the case, having a screenshot to match the one they are stuck on helps tremendously.
- For people following the IG sequentially from the first screen
forward, having a screenshot that looks like the one they are on helps confirm that they are proceeding correctly and makes them feel confident that they are performing the installation correctly.
- Users find it useful to see sample data entered into the sample
screenshot even if it is listed in the text. Some people just learn better visually.
That seems reasonable. It's nice to have one screenshot to show the whole GUI, if that helps. It's probably better to have too few screenshots than too many.
That being said, whoever is taking the screenshots should take them all and a few extra just in case we decide it is actually needed later. This will keep the size and sample data entered consistent throughout the screenshots.
Wise suggestion.
On Fri, 2004-08-27 at 23:33, Paul W. Frields wrote:
- PNG format. Is that too obvious?
No Paul, it needs saying!
- No wider than 500 pixels. If your graphic is larger than that, use
GIMP (Image -> Scale Image) or mogrify to scale the image to no wider than 500 pixels. 3. Graphics should be included as <figure> I think.
With full alternatives to make it work in html.
<figure float="0" id="fig1007"> <title>Block and Inline graphics</title> <mediaobject> <imageobject> <imagedata id="fig10-7" fileref="images/fig10-7.png" format="PNG"/> </imageobject> <textobject> <phrase>Two graphics, one as a block, one as an inline.</phrase> </textobject>
</mediaobject> </figure>
- Graphics should not be included unless you absolutely *cannot* get
along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?)
+1 (accessibility)
-- Paul W. Frields, RHCE
-
Dave Pawson -
Karsten Wade -
Paul W. Frields -
Stuart Ellis -
Tammy Fox