Introduction#

Topics should be made as simple as possible, but not simpler. This one suggests some organizing principles seen on Stack Overflow Documentation.

Language feature Topics

A natural division is simply to make one topic for each language feature. For instance, Python has:

• Classes
• Functions
• Generators
• Decorators
• …

On the downside, features can be quite complicated and it’s easy to come up with many more examples than make sense for a single page. Classes has 16 examples, for instance. Some of those could probably be moved to other feature topics, such as Inheritance, Properties, Methods, etc.

Grab bag Topics

Some topics are loosely associated examples under a theme, such as C# 6.0 Features and Common pitfalls. On the whole, this style of topic has been discouraged since examples per topic were limited as there’s no natural place to stop adding content.

It’s probably better to move the examples to another Topic (perhaps for language features). I haven’t seen this done, but it’s possible these topics could be converted into a meta topic that includes an example or two that consists largely of links to other topics or examples:

Perl Tips and Tricks

• Don’t parse XML with a regex! Use an XML parsing module.
• If you need to comment out whole blocks of code, use a POD comment block.
• …