Date: Mon, 20 Aug 2001 23:51:13 +0200 From: Geert Poels <Geert.Poels@skynet.be> To: Murray Stokely <murray@FreeBSD.org> Cc: freebsd-questions@FreeBSD.org, freebsd-doc@FreeBSD.org Subject: Re: About printed books Message-ID: <5.1.0.14.0.20010820230418.00aa9670@pop.skynet.be> In-Reply-To: <20010820132822.I1174@windriver.com> References: <5.1.0.14.0.20010819161255.00ab07a0@pop.skynet.be> <5.1.0.14.0.20010819161255.00ab07a0@pop.skynet.be>
next in thread | previous in thread | raw e-mail | index | archive | help
--=====================_6453137==_.ALT Content-Type: text/plain; charset="us-ascii"; format=flowed > > A site like http://www.iuniverse.com/marketplace/default.asp > > has a few printed versions but only those. > The FreeBSD Developer's Handbook is nowhere near being polished >enough for publication in a printed form. It's pretty bad even for an >"informal" techpubs company like fatbrain or iuniverse.com. I'd >really like to see this book printed in 12-18 months, but there is a >LOT of work to be done before its ready. Please help us finish >writing it! Since I have close to nothing to write on this topic (because I'm rather a learner), I'd like to be a proofreader. Other assistance would be quality control, giving ideas and maybe helping layout. Let me first make a quick sidestep : ---------------------- First of all, the Doc. project homepage (http://www.freebsd.org/docproj/docproj.html) and subsequent pages are uneasy to navigate. A lot of scrolling could be avoided by creating a left side menu (without going into frames). Also the content, while technically accurate, doesn't guide the reader as much as could be. As an example take the submission page : http://www.freebsd.org/docproj/submitting.html Lets take the first part of the pages : I have written some documentation. How do I submit it? Only in the second half there's the next part about changes to existing docs. Make this choice right from the beginning. First, thank you for taking the time to do this. You should make your documentation available for review. If you can, put it on an FTP site or a website. Then post a message to the -doc mailing list, with a brief outline of the documentation and the pointer to its location, and solicit feedback. What's the URL ? I can be simply inserted. If, for some reason, you can not put the documentation up for FTP or on a web site somewhere you can send it directly to the -doc mailing list. If you do this, please only send plain text documents. These lines should be put two lines up. You should probably cc: this request for comments to other appropriate mailing lists. For example, something that relates to how to use CVSup to keep your source tree up to date would be of interest to the subscribers of the FreeBSD-current and FreeBSD-stable mailing lists. Link to a page with these lists. After people have looked over your documentation, and you have had the chance to incorporate any of their suggestions, you are ready to submit it. Use a numbered list to more easily read the steps. Next : IMHO, the main use of the main docproject page should be to explain to people with information how they can submit this. For the more dedicated writers, more details on the format, styleguide, ... . The menu should be something like - How to submit documentation/changes - Volunteer - About the doc project Not much more. Then gradually, more details on the format, etc. can be prevailed. One time submitters shouldn't be scared away with an SGML overdose. It's about guiding the donator. :-) One never gets the impression the documentation project is 'living'. ----------------------- About the developers book. The biggest part will probably be to get the content filled. Maybe it's kinda big undertaking but IMHO, best would be if A LOT of the FBSD developers overlooked or read the current version (again). Just proofreading is already worth a lot. Geert --=====================_6453137==_.ALT Content-Type: text/html; charset="us-ascii" <html> <blockquote type=cite class=cite cite>> A site like <a href="http://www.iuniverse.com/marketplace/default.asp" eudora="autourl">http://www.iuniverse.com/marketplace/default.asp</a><br>; > has a few printed versions but only those.<br> The FreeBSD Developer's Handbook is nowhere near being polished<br> enough for publication in a printed form. It's pretty bad even for an<br> "informal" techpubs company like fatbrain or iuniverse.com. I'd<br> really like to see this book printed in 12-18 months, but there is a<br> LOT of work to be done before its ready. Please help us finish<br> writing it!</blockquote>Since I have close to nothing to write on this topic (because I'm rather a<br> learner), I'd like to be a proofreader.<br> Other assistance would be quality control, giving ideas and maybe helping layout.<br><br> Let me first make a quick sidestep :<br> ----------------------<br> First of all, the Doc. project homepage (<a href="http://www.freebsd.org/docproj/docproj.html" eudora="autourl">http://www.freebsd.org/docproj/docproj.html</a>)<br>; and subsequent pages are uneasy to navigate.<br> A lot of scrolling could be avoided by creating a left side menu (without going into frames).<br> Also the content, while technically accurate, doesn't guide the reader as much as could be.<br> As an example take the submission page :<br> <a href="http://www.freebsd.org/docproj/submitting.html" eudora="autourl">http://www.freebsd.org/docproj/submitting.html</a><br><br>; Lets take the first part of the pages :<br> <font size=5><b>I have written some documentation. How do I submit it?<br> </b></font><font color="#0000FF"><i>Only in the second half there's the next part about changes to existing docs.<br> Make this choice right from the beginning.<br> </i></font>First, thank you for taking the time to do this.<br><br> You should make your documentation available for review. If you can, put it on an FTP site or a website.<br><br> Then post a message to the -doc mailing list, with a brief outline of the documentation and the pointer to its location, and solicit feedback.<br> <font color="#0000FF"><i>What's the URL ? I can be simply inserted.<br> </i></font>If, for some reason, you can not put the documentation up for FTP or on a web site somewhere you can send it directly to the -doc mailing list. If you do this, please only send plain text documents.<br> <font color="#0000FF"><i>These lines should be put two lines up.<br><br> </i></font>You should probably cc: this request for comments to other appropriate mailing lists. For example, something that relates to how to use CVSup to keep your source tree up to date would be of interest to the subscribers of the <font face="Courier New, Courier">FreeBSD-current and FreeBSD-stable mailing lists.<br> </font><font face="Courier New, Courier" color="#0000FF"><i>Link to a page with these lists.<br> </i></font>After people have looked over your documentation, and you have had the chance to incorporate any of their suggestions, you are ready to submit it.<br> <font color="#0000FF"><i>Use a numbered list to more easily read the steps.<br><br> </i></font>Next : IMHO, the main use of the main docproject page should be to explain to people with information how<br> they can submit this. For the more dedicated writers, more details on the format, styleguide, ... .<br> The menu should be something like <br> - How to submit documentation/changes<br> - Volunteer<br> - About the doc project<br><br> Not much more.<br> Then gradually, more details on the format, etc. can be prevailed.<br> One time submitters shouldn't be scared away with an SGML overdose.<br><br> It's about guiding the donator. :-)<br><br> One never gets the impression the documentation project is 'living'.<br><br> -----------------------<br><br> About the developers book.<br> The biggest part will probably be to get the content filled.<br> Maybe it's kinda big undertaking but IMHO, best would be if A LOT of<br> the FBSD developers overlooked or read the current version (again).<br> Just proofreading is already worth a lot.<br><br> Geert</html> --=====================_6453137==_.ALT-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5.1.0.14.0.20010820230418.00aa9670>