One of the most common frustrations we’ve found when onboarding new devs at OpenCraft is a general sense of feeling ‘lost’ when encountering the devstack for the first time. While there’s no substitute for working with it for an extended period, we felt it would be helpful to write up a little guide article that walks through the structure of the devstack and common commands that new devs may find useful. We thought those in the community would like to know about it.
Thanks! I’ve not installed a theme using that method (I don’t think). How would you go about it? Do you clone a theme repo in the edx-themes directory and then update some settings? Which ones? Have an example theme repo I can clone to give it a try?
Or maybe I should just mention that you can do it and point to a more in depth part of the docs? Theming seems used less often but it’s good to know it’s there.
Btw, since there is currently work being done to create/improve a shared onboarding course for new Open edX developers, maybe this could be incorporated there? @omar@nimisha What do you think?
@Fox_Piacenti Thanks for taking the time to write this up!
In terms of location of this content, I’m wondering whether we can merge it with the README and docs that are already in the devstack repo.
One of the principles we called out in our Developer Docs Requirements, is “co-location” of docs with its relevant code. The assumption is that co-location will enable long-term maintenance of the doc. Otherwise, the code and the doc will get out of sync.
I’d also add that duplicative reference information can be confusing for developers - especially when they onboard. Note that both the blogpost and the devstack README have a “Getting Started” section.
So I’m wondering if there’s an opportunity to use the work you have done and merge it with the Devstack docs. Maybe with the README and the /docs folder? Or you may have better ideas.
I’ve been mulling over this. The problem of the devstack, as I see it, is that a lot of the most important information/pertinent information to new developers is scattered. The README at current does give good setup instructions, and covers a handful of commands, but not as many as I’d expect a new developer to need.
My feeling is that perhaps we should be removing almost all of the contents of the README and pointing to the readthedocs build instead, and that this should contain the getting started section, perhaps with a quick reference in the manner I’ve made with the blog post. In fact, I missed the link entirely because my eyes skimmed down and saw documentation I could immediately use. I was not even aware there was further documentation for the devstack than the README.
Does this seem sensible? I think we could look into better consolidating the docs that way.
