Problem/Motivation

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.

Proposed resolution

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.

Comments

patcon’s picture

patcon CreditAttribution: patcon commented

And yes, much of the diatribe above is do-able without any changes to d.o, but the issue is more about creating a process by which documentation is a first-class citizen as far as devs are concerned, with a canonical source that is within reach of the daily tools they use most naturally :)

dww’s picture

dww
we/he/they
CreditAttribution: dww commented

I once inherited a module with a TODO list file in CVS (yes, back in the day). I quickly discovered this was totally unworkable. The file is totally out of sync across branches. As you add/remove stuff from the list, you either have to merge or patch the file on multiple branches, etc. So, I moved this TODO list to a g.d.o wiki node and removed it from CVS. Sure, that node is stale now, but that's b/c I no longer really care about the module itself. ;)

So although I support the basic premise of this issue (it'd be great if folks treated docs with as much care as their code), I think the actual proposal here would be both a mess to implement, and would actually make it harder for devs to keep things properly documented on all but the most trivial projects with a single branch. Once you've got multiple branches, which branch's copy of the project description (for example) would we display on the project node? What about all the other stale project descriptions in other branches when folks download the D6 version or check it out from Git? Ugh.

Sadly, my vote is "won't fix", even though I'd love to facilitate devs keeping their docs updated. I just don't see this as a good way to do it.

patcon’s picture

patcon CreditAttribution: patcon commented

Thanks for the thoughtful reply dww :)

I understand the concerns, but I think a proper process could accommodate for many of them. To be fair, TODO.txt is one of the most in-flux docs possible (and most on d.o don't use it), so that seems a little unrepresentative. After all, itis a doc for things we want (not things in code), so if any data is going to have ambiguous and confusing branch placement, it's the "wants" list. It's more straightforward when the documentation corresponds to actual code. It shouldn't be committed to any place that the relevant code still isn't.

But hey, I do respect your feelings on it, even though I'm in disagreement. Thanks for hearing me out man

dww’s picture

dww
we/he/they
CreditAttribution: dww commented
Status: Active » Closed (won't fix)

TODO.txt was just meant as an example to show the problems with tracking these kinds of "docs" in VCS. The frequency of updates is a bad way to measure the effectiveness of this proposal for a given task -- the goal was to increase that frequency. ;) If the problem you're ultimately trying to solve is "I wish the descriptions on project pages weren't so stale" then the solution can't be "it's okay if it's sort of a pain to update, no one does that very often, anyway". ;)

Further, the project description is not necessarily tied to a specific branch at all. If anything, it's precisely the place to describe what's true across all branches (and maybe even explain what the different branches are for). I totally fail to see how that's a good fit for what you're talking about.

I think you're going to have a better fit with stuff like the in-code help system folks have been talking about building for a long time. Make the help docs actually part of the code and then make it easy to see those both inside your site when you're using the module, and perhaps on the d.o docs site, too. But this particular proposal seems like a bad fit, sorry.

Thanks for sharing your ideas, though! Keep 'em coming... we always need more people taking initiative and ownership over the tools on d.o.

Cheers,
-Derek

dww’s picture

dww
we/he/they
CreditAttribution: dww commented

BTW, the thing I was (perhaps cryptically) referring to is here: Help and Curated/Official Documentation System. If you wanted to dive in and help that, you'd be most welcome to contribute!

patcon’s picture

patcon CreditAttribution: patcon commented

Ah ok gotcha :)

And yeah, project description is probably one of the toughest. Would really call for something like the gh-pages branch on github, so it was probably a poor suggestion

The in-code help system sounds interesting though. I'll check it out! Thanks Derek

Component: docs.drupal.org » Other