conan-io / conan-io/docs

Clarify docs on the goal you are trying to achieve

Open
#538 3 comments 0 reactions 0 assignees View on GitHub
complex: low priority: medium stage: queue type: engineering
Dominant language
C++
Stars
125
Forks
382
Avg merge
22h 39m
Merged PRs (30d)
21

Description

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](https://en.wikipedia.org/wiki/Cargo_cult) 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](https://fosdem.org/2018/schedule/event/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?

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the “Getting Started” page and the documentation sections on creating and consuming packages. Review the FOSDEM 2018 Conan presentation and the explanations of conanfile.txt and conanfile.py. Done should make the user’s initial goal, package workflows, and choice or interaction between these files understandable.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.