Devdocs: Documentation Changes Log

[mttjohnson]

I brought this up in a discussion at Magento Imagine 2016 (I'm thinking with Alan Kent @alankent and Tana Berry @tanberry) and I don't know if anything actionable ever happened related to it. It seemed like a good idea at the time so I thought I'd bring it up again in case it just got forgotten about.

There seems to be a lot of changes occurring on the DevDocs site which is great, but it tends to be difficult to keep track of what has changed over time as documentation keeps improving. I might have read all the information on Page Caching a few months back and while it may have had some great content, there has been some more recent details that provide more extensive clarity on the subject that has been published. I can't re-read all the content on DevDocs on a regular basis looking for what has changed (though the updated time stamp at the top right of every page is awesome!). I'm not aware of a great way to keep up with what changes are made on DevDocs both for completely new content, or for improvements to something I may have already read about.

For keeping track of the changes made to the actual software as new versions of Magento are released we can review the EXTENSIVE Release Notes for a version to see what new functionality has been added to the release, fixed, or improved. This works pretty well for minor releases like 2.0 to 2.1 to summarize all the important differences from one version to another.

One distinction between DevDocs and the Magento Digital Commerce software is that DevDocs while related to Magento Digital Commerce has it's own additions and improvements or corrections that are separate from the release cadence of the software itself. Any community involvement in documentation is likely going to be involved after the software is released and started to be used or developed with. It is possible to have a change in documentation that is completely unrelated to any changes in the software, possibly a better way of explaining something, or a correction, or providing some additional details or examples to enhance the understanding.

My suggestion is to have a change log of what is getting published to DevDocs over time so there is a place to review what has been added, corrected, or improved on the documentation site. I also suggest having this referenced on the homepage of the DevDocs site as I feel it is as vital to understand the architecture and release notes as it is to be able to keep up with documentation changes on DevDocs. In addition to a dedicated section, a simple timeline/list along the right side of the homepage is an idea to call out the sometimes massive amount of activity happening on DevDocs and draw attention to the most recent changes and make people aware that they can keep track of the changes through the new section. Highlighting recent changes on the homepage could give the homepage a greater purpose than just a table of contents to summarize the navigation elements.

[erikhansen]

I agree with @mttjohnson that this would be valuable.

Here is an example of where this would have come in handy: a developer on our team was working on a project that upgraded from Magento 2.0 to 2.1. He was working on a model and noticed that PhpStorm was flagging the ->load() method as deprecated after the 2.1 upgrade. None of the developers he mentioned it to were aware this had been deprecated in 2.1. Later that day, he happened to stumble upon a new DevDocs page where this was covered: http://devdocs.magento.com/guides/v2.1/extension-dev-guide/persistent-entities.html If DevDocs had maintained a change log, it is likely that one of our developers would have already known about the ->load() method being deprecated.

[ghost]

It's a good idea in general but we're going to have to nail down the requirements quite a bit before it will work without a lot of manual effort.

Every change we feel is important we tweet about and you get those updates when they happen.

Following are some changes that technical writers feel are important that you probably don't care about:

• Yesterday I fixed some misspellings and removed a note I thought was misleading.
• I'm about to change the organization of the Install Guide a little bit.
• I might reorganize a guide without changing any of the contents.

Suggestion: I'm kind of Git ignorant so I might say this the wrong way but have you tried using git log to find a list of changes over time and look at those changes to see if they interest you?

If that's unworkable then we'll need a specific list (more specific than @mttjohnson provided above) that you think should be included in a changelog.

Thanks

[ghost]

@mttjohnson @erikhansen So far I see the following requests:

• Deprecations
• Page Caching (which unfortunately has not been updated yet)

What else?

[hostep]

Ah great question @mttjohnson, I also requested the same thing a couple of days ago (last paragraph).

@xcomSteveJohnson: I'm afraid you can only accomplish something like this manually and not by using scripts, because we only need "important" changes in the changelog. For example:

• a new topic is added
• an existing topic contained incorrect information that has now been corrected
• an existing topic has had some important information added

We don't need these things in the changelog:

• typo fixes
• reorganized content

Also since you say you already tweet about this (where is that btw?), maybe try to remember that everytime you tweet about it, you add it to the changelog?

Using git log is not very user friendly. The changelog is not only important for developers (who know how to work with git), but can also be very useful for project managers, marketeers, shopowners, ...

Another thing which could be helpful and _can_ be automated might be something like this:
You provide a page where all the different pages of the entire devdocs are listed, and you sort them by last modified date and format it like:

• [2016-08-20 19:32:00] - Page A
• [2016-08-20 17:24:00] - Page C
• [2016-08-19 13:57:00] - Page B
• ...

Something like this would also already help out a bit, but a manual changelog is better in my opinion. Or do both?

Thanks!

[ghost]

Thanks, we're tracking this request. If anyone else has input, please let us know.

[erikhansen]

@xcomSteveJohnson I agree with @hostep that creating a manual changelog will be necessary in order to provide value to the community. I like @hostep's idea of a weekly (or every other week?) changelog outlining new pages or notable changes to existing pages.

[ghost]

@erikhansen @hostep This is done now: http://devdocs.magento.com/guides/v2.1/magento-devdocs-whatsnew.html

Feel free to reopen with comments if you'd like to see improvements.

[hostep]

Thanks Steve, good job!

[ghost]

@hostep Thanks. Let us know what you think about the weekly updates. Is it useful? Necessary? IOW, I could always update it every week but is the "Week ending" column useful?

[hostep]

It is certainly useful and necessary :)
I would suggest you change the "week ending" column to the exact date on which the change was published if possible, that makes more sense to me.

Maybe @erikhansen, @mttjohnson and other watchers can also weigh in their opinions?

( I just noticed a small bug btw: the headers of the October changes are shuffled around ;) )

[ghost]

@hostep Can you elaborate on the October changes bug?

[hostep]

Sure, the first column of the October table is "Week ending" instead of "Description", and the other column headers are also incorrect.
See:

[ghost]

Doink. Just pushed the fix, it should be live around 1:45 Central. Thanks!

[mttjohnson]

The what's new section is awesome!

As @hostep mentioned it would be ideal to know the specific date the change was published, as opposed to the week, but considering getting that granular might require a lot more work in the process, the weekly granularity seems more than adequate for what I would think most people would need or want considering this is a summary of changes.

[erikhansen]

@xcomSteveJohnson I agree, that "What's New" section looks great! Good work on that. Thanks for making our lives easier!

[ghost]

@erikhansen @mttjohnson @hostep Thanks for your kind words. We aim to please!

I'm checking into adding the date of each change. If we do that, it would be going forward only.