lts-doc: sort documentation alphabetically

[tflanagan]

As a follow up to #3651, and to #393, I've started from the top and am working my way down.

This is a WIP! Against v4.x!

I am posting this now because it is a big diff and will need eyes.

Docs that have been completed:

• assert
• buffer
• child_process
• cluster
• console
• crypto
• dns
• filling in as I go

Help is more than welcome!

[Fishrock123]

Awesome!

[tflanagan]

Fixed.

[Trott]

/cc @nodejs/documentation

[jasnell]

Note that this cannot land directly against v4.x, it would need to land against v4.x-staging.

Also, my concern with this is that if the equivalent changes are not made in master, it will become much more difficult to simply cherry pick commits for doc changes from master to v4.x-staging in the future. Ideally, these changes would land in master first, then get cherry-picked and modified back in a PR to v4.x-staging.

/cc @nodejs/lts

[tflanagan]

With that comment, @jasnell, I'm holding off on more changes I'm doing the easy ones.

Are you saying I should checkout a new branch off of master and make the changes there? I figured that with master being at v5/v6, the changes in the docs would be too much for backporting.

[jasnell]

I don't want to discourage the work, it's good stuff. However, the process we've been following the landing in Stable and LTS branches is to first land things in master then cherrypick back to the relevant branches. For LTS, the commits land first into v4.x-staging and are pulled into the v4.x only when a release is actually cut. This gives us the most flexibility when we need to do quick releases to address things like security updates, etc. By landing things in master first, it's easier for us to backport future commits.

For instance, if we go through a reorder everything in v4.x but don't make the corresponding change in master, then someone goes and makes edits in the same doc in master, when it's time to pull those back we end up having to reconcile a number of conflicts as opposed to a simple git am with a few tweaks here and there.

Right now, the deltas between v5/v6 are small enough that pulling stuff back to v4 is simple. It will get more difficult as the gap widens but even then, we want to minimize the differences between v4 and master as much as possible. As we go along, there will be changes that need to be made that only apply to v4. Those would still need to land as commits to v4.x-staging.

I don't want to discourage this work, however. It should just be done in a way that ensures parallel changes are being made in master and v5.

[tflanagan]

Okay, @jasnell, so the action to be taken is to open a PR against master?

If so, I'll start the diff/merge on my end, close this (actually I can't), and open a new PR against master.

[jasnell]

Yes. And I would recommend one commit per file modified the way you've been
doing it. Thank you. I know it's a pain.
On Nov 3, 2015 6:17 PM, "Tristian Flanagan" notifications@github.com
wrote:

Okay, so the action to be taken is to open a PR against master?

—
Reply to this email directly or view it on GitHub
#3652 (comment).

[tflanagan]

closing.

re: #3662