Bug 1029712 - Suggestions for documentation improvement.
Summary: Suggestions for documentation improvement.
Keywords:
Status: CLOSED NOTABUG
Alias: None
Product: Fedora Documentation
Classification: Fedora
Component: install-guide
Version: devel
Hardware: All
OS: Linux
unspecified
low
Target Milestone: ---
Assignee: Petr Bokoc
QA Contact: Fedora Docs QA
URL:
Whiteboard:
Depends On: 994794
Blocks:
TreeView+ depends on / blocked
 
Reported: 2013-11-13 00:53 UTC by Ruediger Landmann
Modified: 2014-12-16 17:09 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of: 994794
Environment:
Last Closed: 2014-12-16 17:09:57 UTC
Embargoed:


Attachments (Terms of Use)

Description Ruediger Landmann 2013-11-13 00:53:57 UTC
Thanks Leslie:

Cloning to separate the Document Conventions suggestions from the Install Guide suggestions.

+++ This bug was initially created as a clone of Bug #994794 +++

Improvement recommendation for Install Guide.

http://docs.fedoraproject.org/en-US/Fedora/19/html/Installation_Guide/Installation-Guide-Preface.html#idp16047392

Under 
1.1. Typographic Conventions

The indented paragraph reads
 To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. 

I would replace the word "see" with view. 

    To view the contents of the...

See for me, would be the result of issuing the ls command. See the file, view the contents.

As an aside, for French translation,  "to see" translates to "regarder"  whereas view tranlates to "voir". A similar difference is with Spanish

Please correct for Fedora 20.
======
Further on the same page...

Warnings should not be ignored. Ignoring warnings will most likely cause data loss. 

My comment.

Warnings do not cause data loss. Warnings advise of a situation that if not attended to, will most likely cause data loss. 

=======
Follow page with Introduction
Introduction
This guide covers installation of Fedora, a Linux distribution built on free and open source software.

Please change ... built on ...  to built with. 

My reasoning... You may be on topic, or build on a foundation, but Fedora is built with free and open source software

=======
Another question.  Would you say, "Install Fedora on a computer," or would you say "Install Fedora onto a computer"?   

My preference is to drop the "on a computer".  That would shorten the sentence and accommodate some future hardware device.

=======

2.1.1. How Do I Download Installation Files?
To follow a Web-based guide to downloading, visit http://get.fedoraproject.org/. For guidance on which architecture to download, refer to Section 2.1.2, “Which Architecture Is My Computer?”. 

Would the meaning be more clear if the title started with the word "Of" as in 
"Of which Architecture Is My Computer?"
(sections 2.1.2 and 2.1.3)

--- Additional comment from Pete Travis on 2013-08-08 20:59:31 EDT ---

The "Typographic Conventions" content is defined by publican, the publishing tool used to create the guide.

--- Additional comment from Leslie Satenstein on 2013-08-15 15:36:18 EDT ---

In the installation guide, I noted that chapter two and following that
"the discussion is about downloading the various versions of Fedora (netinstall, dvd, etc)."

Then aas a follow up, there is a long discussion about which version of Fedora is the one to select from a list of options based on architecture and the like.

Should not the latter documentation section precede the downloading information?  As the comments in the guide were "for new users of Linux and experienced ones", the guide may (in my opinion) be presenting information that the individual should know about before downloading or acquiring any version.

Most users of technical manuals do a two pass read.
The first read is to get an appreciation of the product and guide, and the second pass is to follow the recipe.  By following the recipe, it should be
a) step one, determine your version and suitability of hardware
b) step two  determine the version of Fedora you want to install (32bit/64bit) etc.
c) Download/acquire 

....

and so forth.

The guide is almost in the step by step recipe sequence, 

If you go forward, would the improvements be present before Fedora 20,so the new sequence could be ready for a reviewer and his comments?  And if you keep the sequence, I presume the update draft would also be ready for the reviewers and their comments.

--- Additional comment from Leslie Satenstein on 2013-08-15 15:37:32 EDT ---

In the installation guide, I noted that chapter two and following that
"the discussion is about downloading the various versions of Fedora (netinstall, dvd, etc)."

Then aas a follow up, there is a long discussion about which version of Fedora is the one to select from a list of options based on architecture and the like.

Should not the latter documentation section precede the downloading information?  As the comments in the guide were "for new users of Linux and experienced ones", the guide may (in my opinion) be presenting information that the individual should know about before downloading or acquiring any version.

Most users of technical manuals do a two pass read.
The first read is to get an appreciation of the product and guide, and the second pass is to follow the recipe.  By following the recipe, it should be
a) step one, determine your version and suitability of hardware
b) step two  determine the version of Fedora you want to install (32bit/64bit) etc.
c) Download/acquire 

....

and so forth.

The guide is almost in the step by step recipe sequence, 

If you go forward, would the improvements be present before Fedora 20,so the new sequence could be ready for a reviewer and his comments?  And if you keep the sequence, I presume the update draft would also be ready for the reviewers and their comments.

Comment 1 Petr Bokoc 2014-12-16 17:09:57 UTC
We have rewritten almost all of the Fedora Installation Guide, so it no longer makes sense to keep this bug open - it's referring to an old version.


Note You need to log in before you can comment on or make changes to this bug.