Update documentation is incomplete

If there was such a thing as a super-nuclear-critical status for an issue, this issue would be it. As long as these issues exist in that queue, they are completely invisible to 99.9999% of developers. If we want people to start porting en masse we need to make sure we have documentation to support them.

That said, I support tracking this with a single critical issue, so thanks for doing that.

Just realized this doesn't have the right tag. :P

This is the most important issue in the entire queue to work on, for anyone looking for a high-impact task that as a nice side-benefit helps you learn APIs in advance.

D7 pre-release [would-be] critical issues pertaining to documentation (now marked as "normal" instead -- see above).

• #675046: Make sure all hooks in D7 have documentation
• #473268: D7UX: Put edit links on everything
• #553944: Define hook_menu_get_item_alter() as a reliable hook that runs before the page is doomed
• #368516: Fix ambiguity in upgrade.txt
• #614418: Redesign 'Recent comments' block for use on dashboard.
  • · DOWNGRADE??
• #633332: hook API documentation files have no information about where hooks are to go
  • · DUP OF #675046: Make sure all hooks in D7 have documentation??

Can 2 & 3 (and several others) be downgraded since they're either fixed or RTBC? Unless fixed doesn't count as a pending critical issue (though it does show as being "open")... Either way though, I'm sure that the RTBCs count:

http://drupal.org/project/issues/search/drupal?version[0]=156281

&status[0]=1&status[1]=8&status[2]=13&status[3]=14

&priorities[0]=1&categories[0]=bug&categories[1]=task

(More to be added still...)

If feel horribly guilty here. But hey, that's caused by an executive decision to either focus on docs or on *more* clean-ups + fixes. Realistically, which one do you choose? :P ;)

idem :)

Would it be possible to make http://drupal.org/update/modules/6/7 editable by the documentation team? There are a bunch of grammatical things that could do with an edit, as well as linking to related issues.

Really critical to document "presave" for triggers #585868: Triggers/actions need overhaul (part II) - Presave

I will be at that code sprint Friday in Copenhagen and I will work on this.

I visited the upgrade documentation page today intending to use it as a guide to updating my D6 module to D7 and discovered that not only is the documentation incomplete, it is also confusing. Incomplete means that information may be is missing, which I can deal with by just making all of the indicated changes and hoping for the best. Confusing means that the documentation forces me to deal with information that is irrelevant and distracting from the actual needs of someone like myself who simply wants to know how to update modules.

For starters, the documentation begins (after informing me of its own incompleteness) with a long list of changes that are apparently related to specific pre-release versions of D7. I can imagine that this list could be useful to someone, but it isn't helpful to someone who is looking for instructions on how to convert 6.x modules to 7.x, which is the purpose that this documentation page is ostensibly supposed to serve.

Here was my thought process as I encountered the documentation page in its current form: I saw the list of version-specific changes and immediately wondered what I was supposed to do with it. Then I had to wonder why some changes were listed repeatedly under different release versions, and not under others. For example, "Permissions have titles (required) and descriptions (optional)" is listed under "UNSTABLE-1 (2008-Sep-30)," "UNSTABLE-2 (2008-Oct-11)" and "UNSTABLE-10 (2009-Nov-2)" but not under any of the other releases, while "Replace drupal_clone() with clone" is listed under "UNSTABLE-1 (2008-Sep-30)" and not under any of the others. My first thought was, does this mean that "Permissions have titles" was a change that only applied to those release versions and not to the others? Does this mean that "Replace drupal_clone" only applied to the first unstable release and that I'm not supposed to actually make that change when updating my module?

After further review, I realized that each change in the documentation is linked to one or more "needs documentation" issues in Drupal core, and the list of version-specific changes enables me to match each issue to the pre-release version of D7 in which that issue arose. In other words, the listing is a sort of meta-documentation, which I'm sure is useful scaffolding to help in building the actual documentation. The problem is, it is getting in the way of the actual documentation that will be relevant to most module developers like myself. That actual only begins after the long list of version-specific changes that I described above. So why does the documentation page first present us with information that we don't need and is confusing? Can we put that information into a separate "D7 API changes by release version" page so it doesn't create that confusion? Or can we at least move that information to the bottom of the current documentation page, so it isn't the first thing thing that people encounter?

The documentation is also a bit unclear when it says that "Rename user tables" has been postponed. Does this mean that this change won't be happening in the upgrade to D7? Or does it mean that this change won't be happening at all in D7, or does it mean that it will be happening but the D7 team just hasn't gotten around to it yet? If I'm trying to update my module, I'd like to know and not just have to assume. And if this is a change that won't be happening in D7, this change shouldn't be listed at all in the D7 documentation.

I realize that the documentation is a work in progress like the rest of the D7 upgrade, so apologies if my tone here is a bit testy. I'm just a lowly contrib module maintainer. I haven't participated in the work that has gone into developing D7 core, and I certainly appreciate all of the work that other people have done on it. However, i think the fact that I haven't participated in building D7 actually makes me the sort of person that this documentation is intended to serve. Right now it seems that the D7 module upgrade documentation does a better job of serving the needs of D7's core developers than it does of serving the needs of the module maintainers who will actually be using it.

I am changing the tag scheme, because "needs documentation" was being used for all sorts of stuff.

From now on, anything that needs adding to the Update Guide is being tagged "Needs Update Documentation", not "Needs Documentation".

I am also re-tagging the issues in the Needs Update Documentation queue.

There are also a bunch of issues that were never tagged as needs doc/needs update doc. Namely, many issues that were tagged "API Change", then had a patch committed and were marked fixed, but they should have been left at Needs Work and tagged with "Needs Update Documentation".

I also didn't know about this issue, because it should have been in the Documentation component. So moving it there...

Anyway. So there are 3 tasks:

a) Go through the open issues currently tagged with "needs documentation" and change them to "needs update documentation" if what they need is documentation in the theme/module update guide. It would be helpful if the issue has a lot of comments, to add a comment saying exactly what needs to be documented, or point to the comment number where that is stated. And if there is something else that needs documentation, possibly move them into the Documentation component (if it is API doc blocks that need to be written or edited) or file new issues in the Documentation project issue queue (if it is Handbook documentation that needs to be written, aside from the theme/module update guide). In the latter two cases, remove the "Needs documentation" tag, as it's redundant.

b) Go through the issues that are fixed or "closed/fixed" that are tagged with API change, and see if any of them need to be documented in the update guides. If so, add the "needs update documentation" tag to those issues, and change their status back to "needs work".

c) Go through the issues tagged "needs update documentation" and document them in the theme/module update guides.

I am currently working on (a)...

I'm nearly finished with going through the Needs Documentation queue.

Link to search now:
http://drupal.org/project/issues/search/drupal?status[]=Open&issue_tags=Needs+Update+Documentation

subscribe

From #16 - task (a) is done. I'm starting on (b).

Thanks so much for doing this, Jennifer!

Hmmm. I thought I had added a comment here - must have gotten lost.

Anyway. I've finished task (b). "All" that remains is to actually write the update doc for issues tagged "Needs Update Documentation" (see link in #17 for a search).

Going forward, I'll be monitoring the API Change and Needs Documentation issue queues to update status/tags appropriately.

I am going to go ahead and close this issue. Drupal 7 obviously was released without the update doc being completed. Also, the list at http://drupal.org/project/issues/search/drupal?status[]=Open&issue_tags=... is all green except for 4 issues that are currently marked "needs more information". There's not much point in this issue any more, since the main points were (a) block release (didn't happen) (b) motivate contributors to write update doc (didn't happen) and (c) make sure all issues that had api changes were noted in the docs or at least reopened until they were documented (did happen).

I propose demoting un-releasing D7 and tagging it as "still beta after all." That will light a fire under people to take the documentation seriously, and will also help some of the folks who pledged to have their contrib modules ready for D7 release day but didn't actually succeed.

Just joking.

Well... D7 *is* still beta after all, isn't it? I don't think it's just the documentation :-) Not joking. Something over 200 major issues. Many of them lost in 8.x.

RE #23 - I realize you are making a joke, but I'd just like to say that there are only 4 API changes that I am aware of that haven't been documented in the 6/7 module update guide at this point, as compared to the hundreds that were documented -- which is the real reason I'm marking this "fixed".

jhodgdon++
So incredible that you can catch up with these!

jhodgdon++ is right.

Thanks so much for performing this critically necessary but incredibly tedious and oftentimes thankless clean-up work. Let's continue brainstorming on the documentation gate for D8 so that this process doesn't repeat itself ever again.

jhodgdon++

I admire the work that has gone into both developing D7 and the documentation that has been written already, but this documentation on updating is still virtually unusable in its current form. I say this as someone who has upgraded modules from D4.5->4.7, from D4.7->D5, from D5->D6, and most recently from D6->D7. During each previous upgrade, I found that it was pretty straightforward to use the upgrade instructions as a laundry list of things that needed checking and fixing. Here, for example, are the upgrade instructions from D5->D6:

http://drupal.org/update/modules/5/6

There are 82 items on the list that I needed to review to make sure I had fixed everything. OK, it was kind of a long list, but it was doable.

In the case of the D6->D7 instructions, however, not only is the list much longer (a total of 260 items instead of 82), but the "table of contents" at the top of the list is pointlessly broken out by D7 pre-release version. Moreover, some of the items on the list appear multiple times under different releases, while changes that have NOT been made in D7 are also included, which serves no particular purpose other than to further madden any poor soul who tries to use the documentation as actual assistance in helping to upgrade his or her module.

Before you chastise me for not working on this myself, I acknowledge that point fully. In my defense I can only plead that I've been working 70+ hour weeks and just can't make time to work on this too. However, I did squeeze out the time to upgrade one of my contrib modules to D7, and after struggling to use the upgrade documentation, I finally gave up and simply rewrote my module from scratch, ignoring the update instructions and using api.drupal.org as my primary guide.

There's no point in harping on this, because no one is really to blame, but it is nevertheless a problem. There are tons of D6 modules that have not yet been updated to D7, and many of them are important modules whose absence is making it hard for me to update my existing sites from D6 to D7 and making me hesitant to build new sites in it because so much functionality is still missing. The lack of clear documentation is not the only reason why these updates aren't happening faster, but it's certainly a factor.

We're working on this problem over at #648218: Make API changes in Drupal core be nodes.

Re: Sheldon's point at #28: Why don't we move the categorical list at http://drupal.org/node/394070 to the top of http://drupal.org/update/modules/6/7, and move the by-release list to a backup node and archive it immediately. It's more or less useless, but would probably be good to keep around if only to make sure nothing is missing from the categorical list (which is excellent, BTW).

I agree, the categorical list is a huge improvement over the by-release list. I added a bit of detail and formatting to the paragraph at the beginning which explains the status icons for the Coder Review and Coder Upgrade modules, as well as a link to the Coder project page.

#30: The categorical list is not complete, and if you notice, is just a list of titles that has pointers back to the chronological list, so PLEASE don't unpublish or archive the chronological list. If you would like to contribute to finishing the categorical list, that would be helpful. Anything without an [x] on the main list has not been put into the categorical list.

#28 (one small point from your rant) - There is not supposed to be anything in the list that didn't make it into Drupal 7. If you can point out what is there that shouldn't be, we will remove it.

General: We all agree this page is useless as it is. See #649218: new report - equipment usage statistics if you would like to contribute constructively to the work and/or discussion of making it better for next time.

jhodgdon: Regarding stuff in the list that didn't make it into Drupal 7, there is a section on the page subheaded "Rename user tables" which begins, "NOTE: This change has been postponed (see issue links below) and is not included in an 'UNSTABLE-n' list above." I assume that this is referring to a change which was intended for D7 but didn't actually occur. I mentioned this awhile BTW in my rant #15.

Regarding the ranting, I hope it isn't taken personally. I fully appreciate that documentation is a difficult and generally thankless task, and I feel bad that I'm not able to volunteer to help with it myself.

jhodgdon: Couldn't you just cut the chronological list from the top of http://drupal.org/update/modules/6/7 and paste it into a new "archive" node, and then poste in the categorical list from http://drupal.org/node/394070 to replace it?

I realize that you don't, but some people actually find the chronological list useful, for instance if they've been keeping up with d7 development and want to know what has changed since they last checked. Not everyone waits until the release to start working on the new version of their module.

Sure, the chronological list is useful to some people (and it was probably more useful when D7 was still under development), but now that D7-1.0 has been released, I think more people will find the categorical list useful than the chronological list.

And even if the chronological list is useful, it still was not clear. Partly this is because the page didn't provide any instructions explaining even that the chronological list is a chronological list. When someone sees a subhead that says something such as, "UNSTABLE-1 (2008-Sep-30)," they won't necessarily know that this refers to a specific D7 version release. Someone could just as easily interpret that subhead to mean, "These are changes that are are highly unstable, so I'd better wait until they are stable before I try to implement them."

I've gone ahead and added an introductory section to the page which hopefully will make this more clear.

I think the section titled "Rename user tables" should simply be deleted from the page, since it refers to changes that were not actually introduced in D7. However, I thought I should hold off on deleting it myself just in case there is some reason of which I am unaware for keeping it.

Thanks for the header, that's fine. Please don't edit the rest of the page. I don't know who put it there or why, but I'm loathe to remove it. Normally we do wait until something gets committed to add to this page. You could go comment on the referenced issue if you would like more information...

Anyway, this whole "system" is hopefully going away very very very soon. Please, no more discussion here. Please. Please. Please.

Offending section is removed.