search

WellDone / MoMo-Firmware

Embedded PIC Firmware and hardware designs for the WellDone Mobile Monitor (MoMo).
welldone.org
Other
8 stars 6 forks source link

add some clarifying language for beginners, fix bad link, correct typo #145

Closed kgcooke closed 9 years ago

kgcooke commented 9 years ago

Hi guys,

In addition to the edits below, I also wanted to mention:

1) At first I didn't realize that I should be typing the commands into my Git Bash terminal. I could tell that the text in the gray boxes were commands, but I didn't know where to type them in (complete newb here). If you expect other complete newbs, it might be good to be explicit and say "Throughout this document, text in gray boxes should be entered into your Git Bash terminal"

2) When running modtool list (line 60 below), I didn't have the tools/bin set up in my path, so I was encountering issues with this. Actually, I'm still encountering issues with this, even though tools/bin does show up when I do the 'echo PATH$' command... not sure what could be the issue.

amcgee commented 9 years ago

@kgcooke, thanks for the feedback!

Some of your edits aren't technically correct, I'll make comments on the individual changes and can go over them with you if you want.

Regarding your additional comments:

1) Code blocks (the gray boxes) just offset something as a "quote" of sorts, they aren't all going to be terminal commands. Terminal commands should be obvious by the $ or > preceding command lines, or in context, and the concept of running commands in a terminal should probably be a pre-requisite for most people using this documentation - it's common practice for similar developer documentation (see Vagrant documentation, Python documentation, etc.) We can maybe add a sentence somewhere linking to a very basic unix command line introduction or something...

2) If you're referring to the : No such file or directory error when running modtool (as opposed to the previous command not found error) that actually has nothing to do with the PATH variable, which is only used by the bash shell to find the command to run. It is, instead, the product of syncing the source on Windows (which syncs Windows line endings on all the files) and then interacting with it in a Linux Virtual Machine, where Python is expecting UNIX line endings (see this Stack Overflow topic). This isn't trivial to fix, since when you sync the files locally there's no way to tell if you're going to want to use it on Windows or spin up a VM and use it that way, but we should at least address it. We should probably have a Troubleshooting FAQ section.

Do those make sense to you?

More explicit comments coming on the proposed changes.

kgcooke commented 9 years ago

Ok, cool, thanks for the clarifications. It sounds like a FAQ/Troubleshooting section is a good idea. The error I see when I don't include 'python' in front of my momo commands is ": No such file or directory".
As for running commands like 'python momo' or 'python modtool' through the momo_modules/mainboard folder, the error I get is "python: can't open file 'momo': [Errno 2] No such file or directory." These commands work fine from the tools/bin folder, but not the /mainboard folder, despite having added tools/bin to my path. Is this non-trivial issue that you are referring to Austin? If you expect others to encounter this issue, then I suppose it would be best to hash through it and include it in the FAQ/Troubleshooting section as you suggest.