Namespaces
Variants
Actions

Talk:Main Page

From cppreference.com
Revision as of 13:54, 18 September 2013 by FJW (Talk | contribs)

Contents

Guidelines

Initial sketch

I've put up some content to try out things a bit. This should make the discussions about the C++ book more productive. Also, it can be a good starting point.

Note: the current content is only a sketch. It does have major flaws. If you think it can be improved, just edit it, or open a discussion here if you're unsure.

I've spent some time thinking about the issues raised and the solutions proposed in the discussion that followed the initial proposal. One thing is clear: most of the problems can be solved by not having a rigid structure. We should strive for as much flexibility as possible. A good way to achieve this is to have a lot of small, independent items, that we can later rearrange as we want without much effort. This requirement is covered by the following points, which could serve as a starting point of our guidelines after improvements:

  • The content is divided into independent, self-contained items. The basic criteria is as follows: it must be possible to move the item to a separate page without impacting its quality much.
  • Each item has a very limited scope.
  • A single article may contain several items that have similar scope. In some cases this may improve navigation quite a bit.
  • Since there are no warranties that the structure of the wiki will be retained in the future, all items must provide an easy way to get a link to the item though some redirect wrapper, which can be updated in the case item is moved to another page. (This point will be made more concrete when we have such redirect wrapper).

If the above guidelines are met, the high-level structure of the book could be changed on the whim just by rearranging the items in the main page (or in any summary pages). This means that the process of writing tutorials is simplified a lot: one is concerned only with the scope-limited item he's writing now, not the overall structure. Also, we don't need to "design" the structure of the wiki from the start, given that better decisions can be made once the content is available.

The current sketch is divided into two sections: an introduction and the rest of content. The purpose of the introduction is to explain C++ to the readers that have little if any programming experience in C++. This will allow to assume that the reader at least knows the basics in the rest of the wiki, so that we can explain all the peculiarities of one feature or another, without worrying that, e.g. a detailed article about variable scope is read by a reader who doesn't know what a function is.

It won't be possible to easily rearrange the introduction section due to its purpose, but I think that's not a big problem, since the bulk of the content and effort will go to the rest of the wiki.

I think we can start filling in the tutorials in the introduction section. This should reveal any issues with the current approach and allow us to refine the guidelines.

--P12 04:22, 12 September 2013 (PDT)



The main page

Should we have a link to each article in the main page? This will improve discoverability. Since the readers can be assumed to come here to learn something, not to solve a specific issue, we don't need to keep the main page short. But maybe someone knows other reasons for limiting the size of the main page? --P12 04:42, 12 September 2013 (PDT)

I'd imagine that a wall of links on the main page wouldn't hurt, at least while the wiki is still in semi-stealth mode. A link dump is a reasonable starting point that we can use until we figure out how (if at all) we want to do the high-level organization. --Nate (talk) 19:04, 14 September 2013 (PDT)

goto in intro section?

I'm not opposed to mentioning goto for completeness, but should it really be in the "intro" section? New programmers are never going to see it in use, and it seems a bad idea to introduce them to something so quirky, dangerous, and esoteric in an intro book. Not to mention that covering all of its quirks requires a lot more depth than would be available at that point (for example, the interaction of goto and try-catch blocks). --Indi (talk) 10:42, 16 September 2013 (PDT)

I agree. By the way, there's no need to discuss every single bit. You can just go ahead and improve things. I think discussion is worthwhile only for wiki-wide policies, major changes and when there's disagreement. Otherwise a better idea is to invest time in the articles themselves. --P12 13:37, 16 September 2013 (PDT)

Proposal for another structure in the beginners-section

I really like the idea of having a good and free book for people who are going to learn C++, but while the current structure looks better than most of the currently available stuff, I still believe, that it starts to early with some of the low-level-stuff: For instance, I wouldn't teach pointers and build-in-arrays in the beginners-section.

Instead I propose the following structure for the beginners-section (everything not mentioned should instead be covered in the intermediate- or expert-sections):

Note that this uses some C++14-features. The rationale behind that is the fact, that C++11 will be past pretty soon and that there are workarounds for almost all uses that can be noted for people who have old compilers.

Some rationales for this approach:

  • There are enough topics to pack them into some smaller subtopics which may help with recognizing structure while learning.
  • The addition of string and vector to the introduction is the fact, that they enable you to write small programs that already do something. The fact that the basic idea behind strings and arrays is almost trivially to understand for almost everyone is another reason to do that.
  • Moving the for-each-loop further to the front: This loop is another of these small features that makes many things easier and is easy to understand too.
  • Since one should pass arguments to functions by cons-reference in later programs, references and const should be introduced directly after functions. References are again easy to understand and const is important enough to mention it here too
  • Function- and Operator-overloading: I put them where they are mostly in order to keep related things together.
  • IO may be moved bevore functions, I am not sure about that.
  • I believe that basic templates are somewhat easier to understand than virtual functions and that new programmers should get used to them pretty early, beause as the language currently evolves they will become even more important.
  • Enums are relativly related to classes and unlike unions not that dangerous, so I put them there.
  • I believe, that a proper introduction into the STL is very important to teach people into writing good code, so I would dedicate a chapter for that at this point.
  • Since everything in the STL lives in the std-namespace, this might be a good moment, to teach the readers about what namespaces are.
  • blank pointers and manual ressource-managment are a dangerous topic and shouldn't therefore be touched in the beginners-section.
  • Since std::optional will be a very elegant and fast way of returning failure and is somewhat easier to imagine than exceptions, I would introduce it before them.

Opinions? --FJW (talk) 13:54, 18 September 2013 (PDT)