Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Getting Started guide is confusing #280

Closed
WasabiFan opened this issue Sep 9, 2019 · 13 comments · Fixed by #592
Closed

Getting Started guide is confusing #280

WasabiFan opened this issue Sep 9, 2019 · 13 comments · Fixed by #592
Assignees
@salkinium
Labels
documentation 📑 enhancement 🌈

Comments

@WasabiFan
Copy link
Contributor

Hi!

First, I just wanted to say I quite like the look of the modm API and look forward to getting it running. I've been working through testing my scenarios and wanted to share some initial impressions. Once I know more about the library I might be able to come back and open a PR for this.

For now, here's a walk-through of my experience with the onboarding documentation and some thoughts on how it would make more sense to me. It might come across negative. If so, I apologize; that isn't my intent. This is intended to walk through my mindset and might let some confusion through. Either way, I really am just trying to communicate my experience as clearly as possible.

Here's what I see when I open the guide, for reference:

image

When I open the Getting Started page, I see two visible headings: TL;DR and Quickstart. Both of these sections contain only commands that it tells you can be run, getting pretty deep into usage past just setup. The thing is... none of these actually tell you where you run them or how they are supposed to be used, and it turns out that they only work after you have cloned the modm source repository and put it in the right spot. This was confusing point 1: the guide starts with commands without any context for where you run them or what you need beforehand.

Now, assuming I figure out that I need the source and figure out where it should be put, I need to create my project. What files are required for that? As it turns out, it's a main.cpp and a project.xml. But the only way to know that is to scroll down beyond two more headings (ignoring the library code examples, which don't have to manually include modm and therefore are structured differently) and find the on-page example. By this time, you've scrolled through the whole guide and hopefully realized that there's a Your own project heading, which is actually where you need to start: TL;DR and Quickstart both skip over the crucial steps of having modm, source and project files on disk first. This is confusing point 2: If I need to create/clone files, I need to be told that up-front and in-order. TL;DR and Quickstart are both red herrings which distract from the things you need to do.

Now, the Your own project section has good info. But it has four headings (Using a Board Support Package, Discovering modm, Custom Configuration, and Generate and Compile) which don't seem to have appropriate grouping. What I think it's trying to do is present two options: either use an existing BSP for a known board, or make a custom configuration. But why is Discovering modm in the middle? And if a BSP and a custom configuration are mutually exclusive, why are they listed as two peer headings in order? Additionally, Discovering modm has a lot of content and it isn't clear why I need to care as an introductory user. This is confusing point 3: if I'm being presented with mutually exclusive options, I need to be told, and they should be grouped as such. The major steps and order in which they should be done must be clear.

With all that being said, here's my suggestion for a restructuring. Start by moving TL;DR to the bottom, and moving any useful Quickstart content into what's now Your own project. Delete Quickstart. Move the "examples" section to the bottom, above TL;DR. While you're at it, maybe rename TL;DR to Quickstart because that seems like a better name anyway. The current Your own project is now the first section, and should tell you how to a) set up a project directory, b) get the right files in place, and c) run the commands to build. Then you can have a further section/subsection for running it on the device and debugging.

Over all, my suggested structure is:

  • Your first project
    • Setting up a project (renamed from Your own project)
      • Create a directory, clone modm into it, create a subdirectory for the project files, add a default project.xml and main.cpp, and build.
      • The area that gives you default project file contents can link to a separate page or section below with info on not using a BSP. The default should be to use one.
    • Loading and debugging
  • Library examples (links to examples as it is now)
  • Quickstart
    • Show the directory structure and the commands to run with a few sentences between each.

Again, I am nowhere near an expert, so some of this might be wrong/confused/shallow. I'd be happy to talk over ideas and all of this should be taken with a grain of salt; it's only impressions.

Some additional notes on the experience:

  • The nav on the left of the page lists "Getting started" before "Installation", which seems backwards.
  • Neither the installation page nor anywhere obvious on the getting started page makes it clear that the way you use modm in your project is by including its source. And further, none explain that the source isn't used "in situ", but rather a build command makes copies of it after evaluating templates in yet another directory. So if I open these pages, I'm left confused wondering where I'm supposed to get the library from. It would be helpful if there were a paragraph explaining how you get the library, how it's integrated into your own code's build, and how you actually use it.
  • The header formatting on that page is hard to differentiate between h1, h2, and h3.

Thanks! I'd be happy to talk through any of this.
@salkinium
Copy link
Member

Thanks a lot for this feedback, it's very difficult to judge the effectiveness of the docs for me, since my head is so full of implicit design knowledge. I completely agree with your critique. The reason why TL;DR and Quickstart feel so out of place is because it's actually copied from the examples/README.md and thus from a different context. I think the guide tries too hard to describe customization points, that should be separated. I'll rework this on the weekend.

@salkinium salkinium self-assigned this Sep 9, 2019
@WasabiFan WasabiFan mentioned this issue Sep 10, 2019
Open
@salkinium salkinium mentioned this issue Mar 14, 2020
Merged
@blake5634
Copy link

blake5634 commented Aug 9, 2020 •
edited by salkinium
Loading

Related point to this: one of the first steps is to do "lbuild build" but this returns

 lbuild build 
ERROR: Configuration(.): no repositories loaded!
Hint: Add a path to one or more repositories, either in your configuration files:

    <repositories>
      <repository>
        <path>path/to/repo.lb</path>
      </repository>
    </repositories>

Or via the command line:

    lbuild -r path/to/repo.lb discover

The suggested command line (just above) doesn't work either.
(Ubuntu 18.04)

@salkinium
Copy link
Member

lbuild build is meant to be executed in an example, but the getting started guide is bad. I'll prioritize rewriting it, but I'm very busy with work and uni until the end of the year.

@blake5634
Copy link

blake5634 commented Aug 9, 2020 via email

@blake5634
Copy link

blake5634 commented Aug 10, 2020 via email

@salkinium
Copy link
Member

env.Append(toolpath=[r"/home/blake/stm32/modm/tools/build_script_generator/scons/site_tools"

How did you get there? What are you trying to do? Is it a custom project or an example? What does your project.xml look like?

You cannot use our SCons build tools in their raw state, they must first be processed by lbuild build to specialize to the selected target (the generated tools are very different for AVR and STM32). The generated tools are located in modm/scons/site_tools which is typically placed in the same folder as your project.xml.

Ubuntu 18.04 still has Python2 as default, so SCons will use the Python2 interpreter, unless you're using SCons 4.0 (Python 3 only) or explicitly call scons from Python3: alias scons="/usr/bin/env python3 $(which scons)"
I'm not sure about how a Python3 virtualenv would interact with SCons, I would expect virtualenv to be transparent to SCons though, as it should be to any Python tool.

@salkinium
Copy link
Member

I'm about to give up - the rest of my team seems to be going strong with
Windows.

Ah wait, you're from https://github.com/uw-advanced-robotics right?
So I suspect that the team can compile the same code on Windows, but you cannot compile this on Ubuntu?

What are the errors? Which version of modm are you using? The ARUW modm fork which is 216 commits behind? https://github.com/uw-advanced-robotics/modm

@WasabiFan
Copy link
Contributor Author

I just checked in with others on my team and it sounds like this is a separate project which is using modm by our recommendation. I'll have them follow up privately and see if they can help resolve the setup issue. I don't think we've encountered this particular error, but as you said, we've internally pinned on an older modm build and won't see more recent changes!

The above errors were presumably from stock modm; they won't be using our fork, build system or setup config. We do indeed build on Windows, macOS and Linux but most of our protocols are probably not applicable to upstream or other projects.

Sorry for the confusion! I can appreciate the difficulty in taking issue reports on a rather large OSS project 🙂

@blake5634
Copy link

blake5634 commented Aug 10, 2020 via email

@WasabiFan
Copy link
Contributor Author

@blake5634 I think you might have more luck if you open a separate issue for this -- the thread we're currently in is focused on the text and formatting of the getting started guide rather than troubleshooting a particular error.

@salkinium
Copy link
Member

But I had to add those paths in order to make it find things like the tools.

Ok, so a very important information is right there: You're using a custom SConstruct: <option name="modm:build:scons:include_sconstruct">False</option>
This means there should be a SConstruct checked into the repo next to project.xml.

So what does the custom SConstruct look like? (It should reside in the folder your calling scons from.) Why are you using it? What other SCons tooling are you using?

@blake5634
Copy link

blake5634 commented Aug 10, 2020 via email

@salkinium salkinium mentioned this issue Mar 26, 2021
Merged
13 tasks
@salkinium
Copy link
Member

It's been a long time but I found the motivation to rewrite the guides with your feedback in mind. You can see the result in #592.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@salkinium salkinium

Labels
documentation 📑 enhancement 🌈
Milestone
No milestone
3 participants
@salkinium @WasabiFan @blake5634