Package: release-notes Severity: wishlist Tags: patch I ought to have time to do a second sweep, so I won't worry about followups to my existing bugs yet. Today, another easy one.
Index: moreinfo.dbk =================================================================== --- moreinfo.dbk (revision 11526) +++ moreinfo.dbk (working copy) @@ -6,18 +6,18 @@ ]> <chapter id="ch-moreinfo" lang="en"> -<title>More information on &debian;</title> +<title>More information on Debian</title> This is the one file where I've noticed any cases where I want to eliminate a couple of uses of "&debian;". Anybody who wants to recycle this text for use in another distro is going to have to reword every line anyway, and they'll have an easier time of it if they can find all the distro-name references by searching for the one string "Debian". If they tried rejigging it so "&debian;" expands to Ubuntu or something they'd just get a page full of lies about Ubuntu interspersed with hardcoded references to Debian - there's a nice example in this next bit: <section id="morereading"> <title>Further reading</title> <para> Beyond these release notes and the installation guide, further documentation on -&debian; is available from the Debian Documentation Project (DDP), +Debian is available from the Debian Documentation Project (DDP), See above. whose goal is to create high-quality documentation for Debian users and -developers. Available documentation includes the Debian Reference, Debian New -Maintainers Guide, the Debian FAQ, and many more. For full +developers, such as the Debian Reference, Debian New +Maintainers' Guide, and Debian FAQ. For full Simpler and stylistically better phrasing. For a start, "many more" doesn't match up with non-count-noun "documentation" (and the phrase is repeated later in this page, is redundant with "includes"). In the process of reorganising I've added an apostrophe in the same place as it occurs in the title page of the DNMG, and made the use of definite articles consistent. details of the existing resources see the <ulink url="&url-ddp;">Debian Documentation website</ulink> and the -<ulink url="&url-wiki;">Debian Wiki website</ulink>. +<ulink url="&url-wiki;">Debian Wiki</ulink>. </para> <para> Documentation for individual packages is installed into "Wiki website" is redundant (and here, repetitive). It would also work if we phrased it as "the [Debian Wiki] and [DDP] websites". @@ -30,9 +30,9 @@ <section id="gethelp"> <title>Getting help</title> <para> -There are many sources of help, advice, and support for Debian users, but these -should only be considered if research into documentation of the issue has -exhausted all sources. This section provides a short introduction to these sources +There are many sources of help, advice, and support for Debian users, though +these should only be considered after researching the issue in available +documentation. This section provides a short introduction to these sources which may be helpful for new Debian users. </para> <section id="lists"> Rephrased to make it comprehensible. The old version used "sources" one way, then a different way, then tried to refer back to "these sources" meaning the former. The reference to "research into documentation" was also slightly confusing. @@ -50,7 +50,7 @@ <section id="irc"> <title>Internet Relay Chat</title> <para> -Debian has an IRC channel dedicated to the support and aid of Debian users, +Debian has an IRC channel dedicated to support and aid for Debian users, located on the OFTC IRC network. To access the channel, point your favorite IRC client at irc.debian.org and join <literal>#debian</literal>. </para> Referring to the aid *of* users is ambiguous. In fact usually it's both by and for users, but the side we're talking about is "for". @@ -70,11 +70,11 @@ <section id="bugs"> <title>Reporting bugs</title> <para> -We strive to make &debian; a high quality operating system; however +We strive to make Debian a high-quality operating system; however None of this paragraph is reusable for &randomdistro;. Then the hyphen in "high-quality" isn't completely compulsory, but we mentioned "high-quality documentation" earlier, so be consistent. that does not mean that the packages we provide are totally free of bugs. Consistent with Debian's <quote>open development</quote> philosophy and as a service to our users, we provide all the information on reported bugs at our own Bug Tracking -System (BTS). The BTS is browseable at <ulink +System (BTS). The BTS can be browsed at <ulink url="&url-bts;"></ulink>. </para> <para> There's some debate about the spelling of "brows(e)able", but avoiding the issue makes it sound better anyway. @@ -86,7 +86,7 @@ </para> <para> You can submit a bug report using the program <command>reportbug</command> or -manually using e-mail. You can read more about the Bug Tracking System and how +manually using e-mail. You can find out more about the Bug Tracking System and how to use it by reading the reference documentation (available at <filename>/usr/share/doc/debian</filename> if you have <systemitem role="package">doc-debian</systemitem> installed) or online at the <ulink You can read more by reading the docs? When I read things, my objective isn't to end up having read more, it's to find out about stuff. (This document uses the minority spelling "e-mail", but at least it's consistent about it.) @@ -103,7 +103,7 @@ community. Identifying (and also solving) problems related to the development of the distribution by participating on the development <ulink url="&url-debian-list-archives;">lists</ulink> is also extremely helpful. To -maintain Debian's high quality distribution, <ulink +maintain Debian's high-quality distribution, <ulink url="&url-bts;">submit bugs</ulink> and help developers track them down and fix them. The tool <systemitem role="package">how-can-i-help</systemitem> helps you to find suitable reported bugs to work on. Another extra hyphen for the third repetition of the same phrase. If I could think of a good enough synonym I would substitute it in for (probably) the middle one, but nothing else fits quite as well. -- JBR with qualifications in linguistics, experience as a Debian sysadmin, and probably no clue about this particular package
Index: moreinfo.dbk =================================================================== --- moreinfo.dbk (revision 11526) +++ moreinfo.dbk (working copy) @@ -6,18 +6,18 @@ ]> <chapter id="ch-moreinfo" lang="en"> -<title>More information on &debian;</title> +<title>More information on Debian</title> <section id="morereading"> <title>Further reading</title> <para> Beyond these release notes and the installation guide, further documentation on -&debian; is available from the Debian Documentation Project (DDP), +Debian is available from the Debian Documentation Project (DDP), whose goal is to create high-quality documentation for Debian users and -developers. Available documentation includes the Debian Reference, Debian New -Maintainers Guide, the Debian FAQ, and many more. For full +developers, such as the Debian Reference, Debian New +Maintainers' Guide, and Debian FAQ. For full details of the existing resources see the <ulink url="&url-ddp;">Debian Documentation website</ulink> and the -<ulink url="&url-wiki;">Debian Wiki website</ulink>. +<ulink url="&url-wiki;">Debian Wiki</ulink>. </para> <para> Documentation for individual packages is installed into @@ -30,9 +30,9 @@ <section id="gethelp"> <title>Getting help</title> <para> -There are many sources of help, advice, and support for Debian users, but these -should only be considered if research into documentation of the issue has -exhausted all sources. This section provides a short introduction to these sources +There are many sources of help, advice, and support for Debian users, though +these should only be considered after researching the issue in available +documentation. This section provides a short introduction to these sources which may be helpful for new Debian users. </para> <section id="lists"> @@ -50,7 +50,7 @@ <section id="irc"> <title>Internet Relay Chat</title> <para> -Debian has an IRC channel dedicated to the support and aid of Debian users, +Debian has an IRC channel dedicated to support and aid for Debian users, located on the OFTC IRC network. To access the channel, point your favorite IRC client at irc.debian.org and join <literal>#debian</literal>. </para> @@ -70,11 +70,11 @@ <section id="bugs"> <title>Reporting bugs</title> <para> -We strive to make &debian; a high quality operating system; however +We strive to make Debian a high-quality operating system; however that does not mean that the packages we provide are totally free of bugs. Consistent with Debian's <quote>open development</quote> philosophy and as a service to our users, we provide all the information on reported bugs at our own Bug Tracking -System (BTS). The BTS is browseable at <ulink +System (BTS). The BTS can be browsed at <ulink url="&url-bts;"></ulink>. </para> <para> @@ -86,7 +86,7 @@ </para> <para> You can submit a bug report using the program <command>reportbug</command> or -manually using e-mail. You can read more about the Bug Tracking System and how +manually using e-mail. You can find out more about the Bug Tracking System and how to use it by reading the reference documentation (available at <filename>/usr/share/doc/debian</filename> if you have <systemitem role="package">doc-debian</systemitem> installed) or online at the <ulink @@ -103,7 +103,7 @@ community. Identifying (and also solving) problems related to the development of the distribution by participating on the development <ulink url="&url-debian-list-archives;">lists</ulink> is also extremely helpful. To -maintain Debian's high quality distribution, <ulink +maintain Debian's high-quality distribution, <ulink url="&url-bts;">submit bugs</ulink> and help developers track them down and fix them. The tool <systemitem role="package">how-can-i-help</systemitem> helps you to find suitable reported bugs to work on.