discuss: Re: The C++ HOWTO Review
Subject:
Re: The C++ HOWTO Review
From:
Tabatha Persad ####@####.####
Date:
21 Nov 2002 03:51:41 -0000
Message-Id: <1037850734.14961.493.camel@mysticchild.dbsoftware.com>
On Wed, 2002-11-20 at 15:05, John Levon wrote:
> I have to be honest here: I do not see that document as salvagable. My
> main concern being simply "what is it for, and who is it aimed at ?".
>
> What is the scope of this HOWTO intended to be ? What areas does it
> cover that are not already extensively covered elsewhere ? Can you
> expand on your "extremely relevant" comment ? Whilst C++ is certainly in
> wide use on Linux, I do not know of a significant gap in available
> documentation. I would suggest this is backed up by the lack of useful
> content in the HOWTO: both the inaccurate, misleading editorialising,
> and the redundant and poorly coded string class included in the document
> are entirely unnecessary, even disregarding their technical flaws.
You've mentioned many of the things that I would like to address in the
review. As someone only familiar with the basics of C++, I can say that
it wasn't until I installed Linux that I became interested in learning
more about the programming language, and the tools that are available
for my system. In this respect, for new users, it is relevant. Of
course, this depends on the scope of the document. Please read on.
> To be specific, in its current state the document does not even begin to
> meet criteria 1-3 as set out in the Author's Guide :
>
> http://www.tldp.org/LDP/LDP-Author-Guide/sg-subject.html
>
> So I would like to see a discussion regarding this before even
> considering a technical/language review of the document. The project as
> a whole may well decide that there is in fact no need for such a HOWTO,
> but we can't decide that until we've found out what the HOWTO is
> actually about :)
When I have everyone assembled we'll be talking about the focus of the
documentation, and how to make it more clear. Based on my initial
observations, the C++ HOWTO as it stands now is a combination of several
items: links to C++ resources,the author's own experiences and
solutions, and some conjecture. Aside from any technical issues, the
document would require extensive editing for spelling and grammar as it
is now.
After discussing the intended scope with the author, I found out that
the focus is supposed to be on providing C++ resources to new
programmers. The document does state that prior knowledge is required.
I think that to improve this HOWTO, most of the information should be
removed, and what should remain are the resources, categorized in a
logical way. Perhaps this could be strictly a C++ Resources document.
A new HOWTO should be created which actually aims to teach or explain to
users the fundamentals of C++ programming in a Linux environment
(including information for Windows programming is something I'm not sure
about here). A link could be provided to a new and improved C++
Resource document for further exploration.
Or perhaps the document should be reworked to include Al Dev's links to
the resources in a separate section. However it seems like it would be
more complicated that way.
With a proposed TOC on the way this weekend, we can work to get a better
idea of what the C++ HOWTO should be comprised of.
Please provide some feedback on these initial suggestions!
Thanks,
Tabatha
--
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
