Nathan Hartman wrote on Sun, 15 Mar 2020 22:08 +00:00:
> On Thu, Mar 12, 2020 at 3:01 PM Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> > Nathan Hartman wrote on Thu, 12 Mar 2020 18:15 +00:00:
> > > On Thu, Mar 12, 2020 at 12:36 PM Daniel Shahaf
> > > <d.s_at_daniel.shahaf.name> wrote:
> > > > Shelving is now mentioned in three separate sections: #shelving-
> > > > transition, #checkpointing, #shelving. I am a little disoriented by
> > > > this. Shouldn't #shelving-transition link to #shelving, for one?
>
> (snip)
>
> > - Promote #shelving from h4 to h3
> > - Transform #checkpoint to an #h4 inside #shelving
> > - Reword #shelving-transition to be more explicitly only about
> > "upgrading existing shelves from 1.10/1.11/1.12/1.13 to 1.14"
> > and clearly pointing to #shelving for details about the feature
> > — for example:
> > + Change the subsection's title to "Upgrading 1.10–1.13 shelves to 1.14"
> > + Add an emphasized first sentence similar to the italicized "This
> > article is about the political concept of subversion. For other
> > uses, see [Subversion (disambiguation)]." on
> > https://en.wikipedia.org/wiki/Subversion.
> > - (bikeshed) Rename the anchor #shelving-transition to something that
> > doesn't begin with "#shelving-", since #foo-bar is usually a
> > subsection of #foo
>
> As Daniel points out, shelving was mentioned in three different places. More
> generally, we had information about experimental stuff scattered all
> throughout the release notes. I didn't like that because not only does it
> reduce readability, but it makes it seem as though every other thing is
> experimental and incomplete, when in fact, most of Subversion is very stable.
>
> As I started working to incorporate Daniel's suggestions vis a vis shelving,
> it occurred to me that to solve the above problem, and in keeping with the
> theme of stability and accessibility, we should consolidate ALL experimental
> text into one section.
>
> To make it so, in r1875216 I've added a top-level Experimental Features
> section, moved all experimental stuff there, and in particular, made a pretty
> significant refactoring of all the shelving text.
LGTM, thanks!
> r1875217 improves the look of the end of the document, where we had a bunch
> of h2 sections in rapid succession, none of which contained very much text.
> My ulterior motive here is to make Enthusiastic Contributors Welcome a bit
> more visible. :-)
>
> Feedback welcome.
Not related to your changes, but it'd be nice if the mentions of #svn
and #svn-dev were links, either to irc://chat.freenode.net/ (what's the
URI scheme for IRC/SSL?) or to webchat.freenode.net. We have multiple
examples of both elsewhere on the site.
In fact, all those places would benefit from spelling out the "Don't ask
permission to ask your question" and "After asking, wait for an answer"
aspects of IRC. It might be worthwhile be nice to have a canonical
landing place — e.g., a section on /mailing-lists.html — that both gives
the links and explains these expectations, and then have all other links
point to that one rather than directly to *.freenode.net.
Though of course that's no longer about 1.14…
Cheers,
Daniel
Received on 2020-03-15 23:24:47 CET