After the 1.0 release, the language and standard libraries SHOULD be pretty 
stable. So external documentation should not be a problem in this regard.

[cpp reference](http://forum.nim-lang.org///en.cppreference.com/w/) is THE best 
language and stdlib reference I've ever seen, much much better than the 
Python/NodeJS ones. And it's external documentation.

And yes, it's a C++ reference, so how it handles templates (more like generics 
in Nim), [tons of 
overloads](http://forum.nim-lang.org///en.cppreference.com/w/cpp/container/forward_list/forward_list)
 and version updates etc can be valuable to us. It's human crafted and curated, 
it's detailed and cares what professionals care (like when will 
iterators/pointers be invalidated, who will be responsible to free the memory, 
what is the time/space complexity can we expect from a particular container 
instead of just "suitable for blah blah situation" or even worse "fast enough 
for general usage", etc), and it's based on the C++ standards and is written by 
the language lawyers who do understand the standards instead of "out of 
experience" (making it neutral about implementations between vendors and 
resistant to compiler bugs and undefined behaviors, though Nim is defined by 
implementation and has no multi-vendor problems).

The cppreference website itself is also very featureful (based on MediaWiki 
anyway). It has a proper "search". It has a navigation bar (with everything 
grouped/categorized). Functions are grouped by human, even [under the same 
namespace (modules in 
Nim)](http://forum.nim-lang.org///en.cppreference.com/w/cpp/algorithm). And 
exploring the website by clicking into different categories works damn well 
because everything is mostly in one screen until you click inside for a more 
detailed list or content. Examples are runnable on the cloud (through an 
external service that provides various implementations/compilers to test on) 
and it shows the expected output AND examples can be edited by users to try out 
their ideas (not committed/saved to the page, just "edit and run"). Symbols in 
examples are cross-referenced. It has enough redundancy, mostly for showing 
functions in a different format (for example, the [table at the end of the 
page](http://forum.nim-lang.org///en.cppreference.com/w/cpp/container) is 
redundant to the content of each container's page, but it's pretty damn useful.

We can just steal the design. We can even ask the webmaster of cppreference on 
how it is maintained by the community and how they manages redundancy and learn 
from it.

Reply via email to