[cmake-developers] Make it easier for beginners

[Lectem]

Hi guys.

You've probably seen me whining a bit here and there about why CMake is hard to get for begginers, 
and thanks to Ruslo pushing me to it, I finally got the motivation to be involved and contribute to CMake.
I hope this mail can be the beginning of a thought on the CMake ecosystem, and not seen as a rant.

I'd like to discuss a few issues and learning barriers I've heard in the previous years concerning CMake.
Those problems were even more pointed out recently when Boost decided to switch to cmake.
Most of the time, people will tell you stuff like this (note that I'm not inventing those, as most were told to me by co-workers) :

- "it is too hard to know what I should do, or how to do it right"
- "Many articles are out there, none agree on what to do and the documentation is just an API reference, not a real documentation"
- "Based my CmakeLists.txt on the wiki, and now people tell me it's bad practice"
- "I don't get why it's not finding my stuff, it's frustrating"
- "I managed to get a simple program running, but as soon as tried to add more stuff, nothing was working or I didn't understand the docs"
... And the list goes on.

>From my point of view, it mostly comes from a misconception of what CMake now is and the fact it is hard to learn.
In a sense, it's basicly the same problem as C++. 
CMake can be easy, but is seen as hard by some people because it has many features and ways to express the same thing, and that many people write CMakeLists.txt that do not "embrace modern CMake".

So I'd like to make it easier for these people to learn CMake, and for that I need some pointers and the opinion of the current developpers.
I'll make this a list of questions / proposals on which I need feedback, and try to explain my reasons behind it.

Question : Would it possible to delete the wiki, or reset/reopen it ?
Reason: The wiki is full of old stuff, but we can't register to edit stuff.  Still, people willing to learn will end up visiting it, thinking it gives good advice. "How could it not ? It's the official wiki". At the very least I wish we could add a big red message stating it is outdated and not updated anymore.


Question: Would it be ok to add tutorials to the documentation ?
Reason: That's where most people will start with. Diving in the CMake documentation is hard for beginners.  For example, understanding transitive properties requires that you read most of cmake-buildsystem, which is a lot to digest at once. A tutorial would help people understanding how to use it and more importantly why they should use it.
		

Question: Add examples (in link with the tutorials) ?
Reason : Mostly the same as the previous one, having examples can help people with a quickstart and agree on what is the "latest" command/feature to use for X/Y/Z.

Question: Can we add "Added in / API last updated" fields ? I'm not familiar enough with Sphynx yet to know how we could change the template for this. Or perhaps just add it as text in the rst?
Reason: It is hard to know in what version some functionalities are added, and not everybody can afford to require the latest CMake version (though it would be nice). It would be nice to have this at least for new features in the next version

I hope that little by little we will make CMake easier to use for the community, and to this end I'm ready to spend time updating the documentation, errors and write some tutorials / examples.
I truely believe that it is as important as releasing new features.
My idea is mainly to slowly move/enhance stuff from CGold (https://cgold.readthedocs.io/en/latest/) in the official documentation, so that people can rely on it. (By that I mean that people will more easily trust the documentation than CGold if they are new to CMake)

Lectem
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cmake-developers/attachments/20171021/fba0ad63/attachment.html>