Clarify docs on the goal you are trying to achieve

[liberforce]

As a newcommer, the whole documentation seems to answer the "how?" question, but not the "what?" question. I find that hard to understand because of that, as I have the impression of cargo culting without really understanding what I'm doing.

Let's take for example the "Getting Started" page. It tells you "do this, do that", but not the initial problem you're trying to solve. I had the very same feeling when looking at the FOSDEM 2018 presentation about Conan. It separates "creating packages" from "consuming packages", but when you create packages you may need to consume others so that's confusing. The difference between conanfile.txt and conanfile.py is thus unclear. Should I have one? Which one? Should I have both? If I have both is there one that is used in priority?

I want to use libraries but also want to package mine, so in which case i'm in?

[danimtb]

Hi @liberforce,

Well you might be right about the too focused docuementation in "how?" to do something adn it is clearly done to drive the user to the getting started. I am sure we could stop a little more to explain the whys and completely see what you mean with the problem of conanfile.txt VS conanfile.py.

So, just to explain it here, conanfile.txt is used mainly by consumers, projects that will need 3rd-party libraries without doing too many complex things like managing optional dependencies, "automating" the build proces...

conanfile.py is the natural expension of conanfile.txt, and it can be used only for consumer projects to handle the optional dependencies stated before, or to automate the build process and to to package, I is a more flexible format as you might have seen.

In the end, if you want to package your library and also manage depenencies of it, you will need a conanfile.py. Both formats can live together but it would be something redundant... However, conanfile.py will have preference over a conanfile.txt when not calling explicitly (e.g. $ conan install .).

Summary: Yes, something can be improved here. Thanks! :)

[memsharded]

Hi!

Yes, this might be some effect or bias of being both developers and docs writers, which is very difficult to avoid. Just in case, the docs are also open-source: https://github.com/conan-io/docs, so additions, clarifications or fixes from non-biased contributors (i.e. mostly users, not maintainers) could be very helpful to improve.

[liberforce]

I've already contributed a few typo fixes to the docs, don't worry ;).
I'm currently evaluating conan where I work. If it gets some traction, having better docs will be a pre-requisite, so I may have more time to spend on this. For now I'm basically trying to get a grasp on it :).