We keep tests in version control with our code, as we recognize that tests correspond to specific code revisions. And yet our docs, which also correspond to specific code revisions, we keep most visibly on drupal.org, using a system that must be manually brought up-to-speed with the project codebase after the fact, through a process that is very much out of scope of our development processes.
I feel this leads to different mentalities among devs -- some let the drupal.org docs get out of sync as it's not in the flow of their dev process. Some let the docs in git get out of date as they're not really first-class objects as far as the public-facing website goes. But either way, our documentation strategy seems somewhat less cohesive than it could be.
I think we sometimes underestimate how important it is that we can start writing documentation as we add features -- committing docs as we commit code -- driven by the knowledge that what we write is exposed not just in the repo viewer or local text editor, but prominently visible and indexed on drupal.org itself.
Investigate whether we could be deriving certain aspect of our documentation from sources that are version-controlled within the project code.
I've found the concept of README-driven development to be incredibly helpful, for what it's worth. But it's the sort of process that isn't really fostered with our current modus operandus. Even without writing a rough README first, just being able to document on-the-fly is incredibly useful, as we can associate the documentation process with the actual code-changes in a commit. Once it becomes part of your pre-commit process, it's almost a no-brainer to document, as opposed to an afterthought that we deal with on drupal.org after we've pushed.
It works very well when you can get it in your workflow that when you
git add your files and do a quick
git status check, you consider "Should my README be on that list too?", and if so, you make the relevant changes, and push.
I'm hesitant to suggest any sort of scope until I know how ridiculous this request might be (in light of the git infra that I don't understand yet). If people think it's worth entertaining the idea, I suppose a modest start might be to discuss keeping the project description in git, possibly using markdown format?
Remaining tasks, User interface changes & API changes
Oh god. Do not want.