There is currently an initial draft for a document that is to be considered a Getting Set Up doc for people wanting to hack on Python. But I have a dilemma: how does this and future docs I plan to write tie into the dev FAQ?
For as long as I have been the unofficial maintainer of the dev FAQ it has been primarily used for helping out with svn and SSH. While both tools obviously have their own FAQs all over the Net, the dev FAQ collects exactly what a typical contributor or core developer might need to know in order to work on Python.
But I am beginning to realize there is some overlap in goals. I need to decide what balance I want to strike between the dev FAQ and these narrative docs. One approach is to push all technical details into the dev FAQ, allowing the dev docs to basically be tools-agnostic. This has a certain appeal to me as our switch from CVS to Subversion or from SourceForge to Roundup caused documentation issues for some time after the switch-overs. That way any tool changes can be focused in the dev FAQ.
But not everything is necessarily structured for a FAQ. While I can outline the questions in a certain order to help facilitate people learning what to do, having a basic narrative can be more helpful. So what am I to do?
Take as an example checking out the trunk. Now I can explain how we typically have multiple versions of Python under development in the narrative and then point to the dev FAQ for details on where to find the repositories and how to check out the code. Or I can outline directly in the Setup doc what steps one needs so that it is more like a HOWTO that people just follow.
I could attempt a hybrid where I list the steps at a high-level in the Setup doc with links to the specific questions in the dev FAQ, although that is still brittle in the case where the dev FAQ changes (e.g. we move off of svn to some distributed VCS).
I think I have convinced myself to have the docs be tool-agnostic and move all of it into the dev FAQ. Organization of the information makes sense to me as well as centralizing stuff so that any changes in the future will not be too painful. If people (dis)agree, feel free to say so.
