You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Nathan Hartman <ha...@gmail.com> on 2019/09/12 03:00:54 UTC
Re: Simplifying our documentation
On Fri, Aug 30, 2019 at 11:09 AM Julian Foad <ju...@apache.org> wrote:
> Nathan Hartman wrote in thread "Change to Subversion PMC rule for
> approving backports":
> > Julian Foad wrote:
> >> I strongly urge that we simplify any and all of our documentation at
any
> >> opportunity. Nearly all of it is much too long. It would be much better
> >> to state the facts in a few bullet points, and move the discussion of
> >> rationale and history to a dedicated subsection so readers just wanting
> >> the facts can easily skip that part.
> >
> > Which document would you consider most important to fix the soonest?
>
> In line with current transition to emphasise stabilization and
> availability, I suppose these user-facing docs should take priority:
>
> * finding/downloading/installing svn from *binaries*:
> - http://subversion.apache.org/packages
>
> * how to contact us; reduce/combine some of these?
> - http://subversion.apache.org/reporting-issues
> - http://subversion.apache.org/docs/community-guide/issues
> - http://subversion.apache.org/mailing-lists
> - http://subversion.apache.org/docs/community-guide/mailing-lists
> - http://subversion.apache.org/faq#more-information
> - http://subversion.apache.org/security/
>
> * and the home page should make those things extremely easy to find:
> - http://subversion.apache.org/
>
> If you or anyone wants to help, I think any of those would be an
> excellent place to do so.
>
> The various contact info is particularly scattered, and pointers often
> state "users@" email with no hint of the IRC/Matrix alternative. Could
> we make a good "contact us" landing page which directs users
> appropriately to all forms of contact?
I've been studying the site and there is a site-ng branch created 2015. I
remember a discussion about it around that time but I can't find it in the
archives now.
Since there are no commits on site-ng beyond branch creation / readme,
would it be agreeable if I catch it up to the present and use it?
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Fri, Sep 13, 2019 at 8:18 AM Branko Čibej <br...@apache.org> wrote:
> On 13.09.2019 14:16, Nathan Hartman wrote:
>> If there are no objections I'll remove site-ng and create a branch
>> from staging called staging-ng. I think it should be under site,
>> adjacent to staging and publish, and not under subversion root?
>
> Yes, that's correct.
Deleted site-ng in r1866904.
Added site/staging-ng in r1866905.
Re: Simplifying our documentation
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2019 14:16, Nathan Hartman wrote:
> On Fri, Sep 13, 2019 at 3:08 AM Branko Čibej <brane@apache.org
> <ma...@apache.org>> wrote:
>
> On 13.09.2019 09:00, Julian Foad wrote:
> > Nathan Hartman wrote:
> >> Once there's actually something to show we can cross the bridge
> of either asking Infra (nicely of course) or moving it to a
> subdirectory of staging, with a link to coming soon, preview the
> new site. But let's not get ahead of ourselves.
> >
> > That all sounds good. Just one thing: a new branch that is a
> sibling of 'publish' and 'staging' would seem to be the right
> level. The existing 'site-ng' branch contains virtual copies of
> both, which seems the wrong level, and also catching up and
> re-purposing an old branch makes slightly confusing (and slightly
> inefficient) history. Create a new one!
>
> Yes indeed ... and maybe even create a copy of staging/, not publish/,
> to make future merge history clearer.
>
> -- Brane
>
> Yes. I reached this conclusion also when I ran the merge and realized
> that this is a branch that contains branches. So I didn't commit that
> mess.
>
> If there are no objections I'll remove site-ng and create a branch
> from staging called staging-ng. I think it should be under site,
> adjacent to staging and publish, and not under subversion root?
Yes, that's correct.
-- Brane
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Sun, Sep 29, 2019 at 11:56 AM Daniel Shahaf <d....@daniel.shahaf.name> wrote:
>
> Nathan Hartman wrote on Sun, 29 Sep 2019 15:48 +00:00:
> > html5boilerplate is under a MIT license:
> > https://github.com/h5bp/html5-boilerplate/blob/master/LICENSE.txt
> >
> > Can this (or snippets from it) be used for Subversion's website?
>
> Yes. https://www.apache.org/legal/resolved#category-a
Thank you.
Re: Simplifying our documentation
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Nathan Hartman wrote on Sun, 29 Sep 2019 15:48 +00:00:
> html5boilerplate is under a MIT license:
> https://github.com/h5bp/html5-boilerplate/blob/master/LICENSE.txt
>
> Can this (or snippets from it) be used for Subversion's website?
Yes. https://www.apache.org/legal/resolved#category-a
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Fri, Sep 13, 2019 at 9:40 AM Nathan Hartman <ha...@gmail.com> wrote:
> Deleted site-ng in r1866904.
>
> Added site/staging-ng in r1866905.Regarding the site/staging-ng branch:
Regarding the site/staging-ng branch:
In the past, I've used two files from html5boilerplate.com:
normalize.css and main.css for other projects.
html5boilerplate is under a MIT license:
https://github.com/h5bp/html5-boilerplate/blob/master/LICENSE.txt
Can this (or snippets from it) be used for Subversion's website?
(Asking because one of my objectives is better display on mobile.)
Matrix [was: Simplifying our documentation]
Posted by Julian Foad <ju...@apache.org>.
Nathan Hartman wrote:
> Are you on Matrix or IRC? [...]
>
> Haven't reached my desk yet today. I'm emailing from my phone. :-)
>
> <https://matrix.to/#/%23freenode_%23svn-dev:matrix.org>
No problem: these Matrix clients work well on mobile:
https://f-droid.org/repository/browse/?fdid=im.vector.alpha
https://play.google.com/store/apps/details?id=im.vector.app
https://itunes.apple.com/us/app/vector.im/id1083446067
- Julian
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Fri, Sep 13, 2019 at 8:21 AM Julian Foad <ju...@foad.me.uk> wrote:
> Are you on Matrix or IRC? It's easier to continue this kind of
> conversation there, if you are. Freenode #svn-dev, or
> https://matrix.to/#/#freenode_#svn-dev:matrix.org
Haven't reached my desk yet today. I'm emailing from my phone. :-)
<https://matrix.to/#/%23freenode_%23svn-dev:matrix.org>
Re: Simplifying our documentation
Posted by Julian Foad <ju...@foad.me.uk>.
Nathan Hartman wrote:
> If there are no objections I'll remove site-ng and create a branch from
> staging called staging-ng. I think it should be under site, adjacent to
> staging and publish, and not under subversion root?
Are you on Matrix or IRC? It's easier to continue this kind of
conversation there, if you are. Freenode #svn-dev, or
https://matrix.to/#/#freenode_#svn-dev:matrix.org
- Julian
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Fri, Sep 13, 2019 at 3:08 AM Branko Čibej <br...@apache.org> wrote:
> On 13.09.2019 09:00, Julian Foad wrote:
> > Nathan Hartman wrote:
> >> Once there's actually something to show we can cross the bridge of
> either asking Infra (nicely of course) or moving it to a subdirectory of
> staging, with a link to coming soon, preview the new site. But let's not
> get ahead of ourselves.
> >
> > That all sounds good. Just one thing: a new branch that is a sibling of
> 'publish' and 'staging' would seem to be the right level. The existing
> 'site-ng' branch contains virtual copies of both, which seems the wrong
> level, and also catching up and re-purposing an old branch makes slightly
> confusing (and slightly inefficient) history. Create a new one!
>
> Yes indeed ... and maybe even create a copy of staging/, not publish/,
> to make future merge history clearer.
>
> -- Brane
>
> Yes. I reached this conclusion also when I ran the merge and realized that
this is a branch that contains branches. So I didn't commit that mess.
If there are no objections I'll remove site-ng and create a branch from
staging called staging-ng. I think it should be under site, adjacent to
staging and publish, and not under subversion root?
Re: Simplifying our documentation
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2019 09:00, Julian Foad wrote:
> Nathan Hartman wrote:
>> Once there's actually something to show we can cross the bridge of either asking Infra (nicely of course) or moving it to a subdirectory of staging, with a link to coming soon, preview the new site. But let's not get ahead of ourselves.
>
> That all sounds good. Just one thing: a new branch that is a sibling of 'publish' and 'staging' would seem to be the right level. The existing 'site-ng' branch contains virtual copies of both, which seems the wrong level, and also catching up and re-purposing an old branch makes slightly confusing (and slightly inefficient) history. Create a new one!
Yes indeed ... and maybe even create a copy of staging/, not publish/,
to make future merge history clearer.
-- Brane
Re: Simplifying our documentation
Posted by Julian Foad <ju...@foad.me.uk>.
Nathan Hartman wrote:
> Once there's actually something to show we can cross the bridge of either asking Infra (nicely of course) or moving it to a subdirectory of staging, with a link to coming soon, preview the new site. But let's not get ahead of ourselves.
That all sounds good. Just one thing: a new branch that is a sibling of 'publish' and 'staging' would seem to be the right level. The existing 'site-ng' branch contains virtual copies of both, which seems the wrong level, and also catching up and re-purposing an old branch makes slightly confusing (and slightly inefficient) history. Create a new one!
- Julian
Sent with FairEmail [https://email.faircode.eu/] , an open source, privacy friendly email app for Android
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Thu, Sep 12, 2019 at 10:45 PM Branko Čibej <br...@apache.org> wrote:
> On 13.09.2019 04:18, Nathan Hartman wrote:
> > On Thu, Sep 12, 2019 at 3:12 AM Branko Čibej <brane@apache.org
> > <ma...@apache.org>> wrote:
> >
> > On 12.09.2019 05:00, Nathan Hartman wrote:
> > > I've been studying the site and there is a site-ng branch created
> > > 2015. I remember a discussion about it around that time but I can't
> > > find it in the archives now.
> > >
> > > Since there are no commits on site-ng beyond branch creation /
> > readme,
> > > would it be agreeable if I catch it up to the present and use it?
> >
> > site-ng was a misguided attempt at changing how our site
> > implementation
> > works (from server-side includes to generated static pages). If we
> > ever
> > do that overhaul, we'll probably use the new templating automation
> > that
> > Infra is working on.
> >
> > I'd prefer to *delete* the site-ng branch. The staging branch is
> there
> > for preparing content changes.
> >
> > -- Brane
> >
> >
> > I know about staging and it's convenient that it's served. But I'd
> > like to experiment without worrying about breaking things. I hope to
> > achieve three things:
> >
> > * Reorganize the information so visitors find what they want with
> > minimal reading and searching
> >
> > * A more modern look
> >
> > * Improve display on mobile phones
> >
> > I'd like to emphasize that I am *not* thinking about changing the
> > implementation (SSI vs something else) at this time. Nor am I thinking
> > about removing or rewriting the text. The information we have on the
> > site is good and thorough. I just want to reorganize it and make a
> > good first impression on visitors with an attractive home page -- and
> > make sure we're all happy with it before it moves to staging.
>
> Oh, then sure, either use site-ng or create another branch, whatever
> suits you best. The only (minor) issue is that you'll have to cook up a
> local server for testing. Or of course we could ask Infra nicely to
> publish yet another branch of our site.
>
> -- Brane
That's the easy part. I have a virtual machine with a LAMP stack. :-)
Once there's actually something to show we can cross the bridge of either
asking Infra (nicely of course) or moving it to a subdirectory of staging,
with a link to coming soon, preview the new site. But let's not get ahead
of ourselves.
Re: Simplifying our documentation
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2019 04:18, Nathan Hartman wrote:
> On Thu, Sep 12, 2019 at 3:12 AM Branko Čibej <brane@apache.org
> <ma...@apache.org>> wrote:
>
> On 12.09.2019 05:00, Nathan Hartman wrote:
> > I've been studying the site and there is a site-ng branch created
> > 2015. I remember a discussion about it around that time but I can't
> > find it in the archives now.
> >
> > Since there are no commits on site-ng beyond branch creation /
> readme,
> > would it be agreeable if I catch it up to the present and use it?
>
> site-ng was a misguided attempt at changing how our site
> implementation
> works (from server-side includes to generated static pages). If we
> ever
> do that overhaul, we'll probably use the new templating automation
> that
> Infra is working on.
>
> I'd prefer to *delete* the site-ng branch. The staging branch is there
> for preparing content changes.
>
> -- Brane
>
>
> I know about staging and it's convenient that it's served. But I'd
> like to experiment without worrying about breaking things. I hope to
> achieve three things:
>
> * Reorganize the information so visitors find what they want with
> minimal reading and searching
>
> * A more modern look
>
> * Improve display on mobile phones
>
> I'd like to emphasize that I am *not* thinking about changing the
> implementation (SSI vs something else) at this time. Nor am I thinking
> about removing or rewriting the text. The information we have on the
> site is good and thorough. I just want to reorganize it and make a
> good first impression on visitors with an attractive home page -- and
> make sure we're all happy with it before it moves to staging.
Oh, then sure, either use site-ng or create another branch, whatever
suits you best. The only (minor) issue is that you'll have to cook up a
local server for testing. Or of course we could ask Infra nicely to
publish yet another branch of our site.
-- Brane
Re: Simplifying our documentation
Posted by Nathan Hartman <ha...@gmail.com>.
On Thu, Sep 12, 2019 at 3:12 AM Branko Čibej <br...@apache.org> wrote:
> On 12.09.2019 05:00, Nathan Hartman wrote:
> > I've been studying the site and there is a site-ng branch created
> > 2015. I remember a discussion about it around that time but I can't
> > find it in the archives now.
> >
> > Since there are no commits on site-ng beyond branch creation / readme,
> > would it be agreeable if I catch it up to the present and use it?
>
> site-ng was a misguided attempt at changing how our site implementation
> works (from server-side includes to generated static pages). If we ever
> do that overhaul, we'll probably use the new templating automation that
> Infra is working on.
>
> I'd prefer to *delete* the site-ng branch. The staging branch is there
> for preparing content changes.
>
> -- Brane
I know about staging and it's convenient that it's served. But I'd like to
experiment without worrying about breaking things. I hope to achieve three
things:
* Reorganize the information so visitors find what they want with minimal
reading and searching
* A more modern look
* Improve display on mobile phones
I'd like to emphasize that I am *not* thinking about changing the
implementation (SSI vs something else) at this time. Nor am I thinking
about removing or rewriting the text. The information we have on the site
is good and thorough. I just want to reorganize it and make a good first
impression on visitors with an attractive home page -- and make sure we're
all happy with it before it moves to staging.
Thoughts?
Re: Simplifying our documentation
Posted by Branko Čibej <br...@apache.org>.
On 12.09.2019 05:00, Nathan Hartman wrote:
> On Fri, Aug 30, 2019 at 11:09 AM Julian Foad <julianfoad@apache.org
> <ma...@apache.org>> wrote:
> > Nathan Hartman wrote in thread "Change to Subversion PMC rule for
> > approving backports":
> > > Julian Foad wrote:
> > >> I strongly urge that we simplify any and all of our documentation
> at any
> > >> opportunity. Nearly all of it is much too long. It would be much
> better
> > >> to state the facts in a few bullet points, and move the discussion of
> > >> rationale and history to a dedicated subsection so readers just
> wanting
> > >> the facts can easily skip that part.
> > >
> > > Which document would you consider most important to fix the soonest?
> >
> > In line with current transition to emphasise stabilization and
> > availability, I suppose these user-facing docs should take priority:
> >
> > * finding/downloading/installing svn from *binaries*:
> > - http://subversion.apache.org/packages
> >
> > * how to contact us; reduce/combine some of these?
> > - http://subversion.apache.org/reporting-issues
> > - http://subversion.apache.org/docs/community-guide/issues
> > - http://subversion.apache.org/mailing-lists
> > - http://subversion.apache.org/docs/community-guide/mailing-lists
> > - http://subversion.apache.org/faq#more-information
> > - http://subversion.apache.org/security/
> >
> > * and the home page should make those things extremely easy to find:
> > - http://subversion.apache.org/
> >
> > If you or anyone wants to help, I think any of those would be an
> > excellent place to do so.
> >
> > The various contact info is particularly scattered, and pointers often
> > state "users@" email with no hint of the IRC/Matrix alternative. Could
> > we make a good "contact us" landing page which directs users
> > appropriately to all forms of contact?
>
> I've been studying the site and there is a site-ng branch created
> 2015. I remember a discussion about it around that time but I can't
> find it in the archives now.
>
> Since there are no commits on site-ng beyond branch creation / readme,
> would it be agreeable if I catch it up to the present and use it?
site-ng was a misguided attempt at changing how our site implementation
works (from server-side includes to generated static pages). If we ever
do that overhaul, we'll probably use the new templating automation that
Infra is working on.
I'd prefer to *delete* the site-ng branch. The staging branch is there
for preparing content changes.
-- Brane
Re: Simplifying our documentation
Posted by Julian Foad <ju...@apache.org>.
Nathan Hartman wrote:
> I've been studying the site and there is a site-ng branch created 2015. I remember a discussion about it around that time but I can't find it in the archives now.
> Since there are no commits on site-ng beyond branch creation / readme, would it be agreeable if I catch it up to the present and use it?
It would be better to use the site/staging branch which you can find alongside site/publish and which is served at http://subversion-staging.apache.org
- Julian