Contributing guide needs to make a few things more clear
- Dominant language
- Python
- Stars
- 58
- Forks
- 160
- Avg merge
- 5d 11h
- Merged PRs (30d)
- 12
Description
I recently got a new computer and had to set up my docs environment again from scratch. It was... not as easy as it should be. This was an eye opening experience.
### ADB
I installed Android Studio first, and then couldn't find where/how to activate "Platform Tools". I think the exact UI has changed since most of the articles we link to were written. Also, the articles we link to aren't great in context of trying to accomplish something. We need to find a better tutorial, or write one ourselves.
Once I got it installed, it wasn't in my bash PATH. I basically understand how execution path works in Bash, and it took me a little while to figure out (a) this was the problem and (b) how to fix it. Someone unfamiliar with bash/terminal would probably have a real problem.
### Git LFS
I remember this being a pain when we first set it up, but then --- you just get a long with things and forget. The local install instructions (from GLFS itself) are not clear at all.
I DLed the tarball and then (I know this sounds dumb) couldn't really figure out what I was supposed to do with it. The Getting Started instructions at https://git-lfs.github.com/ start step 1 assuming you already have it installed.
I eventually figured out it would be smarter to use `brew` (which I then had to install) and then (I have no idea why) I had a problem with `brew link`. This causes some execution path issues that make it seem like its there but then not work with git. Googling around for answers to this turns up a lot of contradictory and out-dated advice. I only got a little confused and hung up here. I can imagine someone who isn't comfortable at the terminal getting very frustrated or abandoning.
### Python / Legacy Python / Virtual Environments
We use Python, not Legacy Python. (That is, 3 not 2).
(cf. https://pythonbytes.fm/episodes/show/5/legacy-python-vs-python-and-why-words-matter-and-request-s-5-whys-retrospective)
Our overly-Mac-focused docs currently assume you will use the Python 2.7 tools to set up your virtual environment. Since you have to have Python 3.x installed anyway before creating the virtual environment, we should probably just write the instructions to use `python3 -m venv odkenv`.
Which brings me to...
#### Local editors and IDEs
On that note --- many editors and IDEs let you run a terminal and/or otherwise execute commands from inside them. This is all well and good until Python virtual environments and execution paths get confused. Or are different than what you previously experienced (or what we documented) on whatever "standard" Terminal emulator.
Some of this would be helped by documenting best practices (like using `.bashrc` instead of keeping everything in `.bash_profile`) and some of it just needs a little more explanation so people can figure things out with more info.
Related to that...
This might not be a thing we want to keep in the docs. (I've thought about a wiki or something for this sort of thing.) But... ReST syntax is not well supported in many editors. Atom support is middling. Emacs is great, but requires packages and setup and all sorts of things. I haven't tried the Python-focused ones but I imagine they handle this all a bit better.
It took me a while the first time around to get Emacs up and running in a way that seemed reasonable, and I imagine other people have taken time to do the same for their local setup. It would be good if we had something (again --- maybe not in the formal docs --- maybe a GH wiki... maybe) where people could share how they are setting up their local authoring environment. If we want to encourage/support new writers/coders, this sort of thing makes a difference.
-----
So those are some of my recent issues. I'll add more as I remember them or run into new ones. If any one else has had difficulty following our setup instructions, commenting here would be a great way to help us improve our docs.
Contributor guide
Research direction
Start by reviewing the contributing guide and the current local setup documentation, then trace the ADB, Git LFS, Python virtual-environment, and editor guidance mentioned in the issue. Compare those instructions with the setup problems described; done means the relevant guidance is clearer and covers the reported installation, PATH, and Python 3 setup obstacles.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash, emacs, git, macos, python
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100