You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficcontrol.apache.org by "Durfey, Ryan" <Ry...@comcast.com> on 2017/09/26 20:56:42 UTC
Apache Cwiki vs. Github Wiki vs. Github Docs
All,
Given the move to Github, I think we should consider moving out of Apache Cwiki. While I think this is a far superior wiki to the offering from Github, I think unifying everything in one environment is a better overall approach. I also wanted to consider foregoing the wiki altogether and suggest pushing this documentation into a new “beta” or “design” section under our docs in http://trafficcontrol.apache.org/docs/latest/index.html . This would unify us into a single documentation format, simplify the transition from design to publication, and eliminate the need to support a wiki altogether.
Would love feedback on this:
1. Move to Github wiki
Or
1. Move to a new “beta” section under http://trafficcontrol.apache.org/docs/latest/index.html
Ryan Durfey
Sr. Product Manager - CDN | Comcast Technology Solutions
1899 Wynkoop Ste. 550 | Denver, CO 80202
M | 303-524-5099
ryan_durfey@comcast.com<ma...@comcast.com>
CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com>
Re: Apache Cwiki vs. Github Wiki vs. Github Docs
Posted by "Eric Friedrich (efriedri)" <ef...@cisco.com>.
I’m pretty solidly against getting rid of the Wiki altogether for the reasons Jan laid out.
I’d also like to know more about the Github Wiki workflow before we make a decision. For example, can someone actually open a PR against a Wiki page?
—Eric
> On Sep 26, 2017, at 8:46 PM, Durfey, Ryan <Ry...@comcast.com> wrote:
>
> And per Nick’s feedback I think most users would be able to submit PRs for document modifications which would need to be accepted by committers. I think that solves the access issue.
>
> The logic of the move from jira to github was to simplify/unify everything to make it so there was less need for system access and less overhead of maintaining multiple sites. In moving to “full” github, everything collapses down into one single system and we can focus on keeping it up to date. It also forces us to use the github publishing system more regularly which should improve documentation output. I think we could still keep informal information in the site we would just create a new section for it that calls out what it is.
>
> If it makes a difference, Ashish and I could port the documentation over to either location so the lift on the developers would be nil aside from feedback.
>
>
> Ryan Durfey M | 303-524-5099
> CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com>
>
>
> From: <ne...@gmail.com> on behalf of NerdyNick <ne...@apache.org>
> Reply-To: "dev@trafficcontrol.incubator.apache.org" <de...@trafficcontrol.incubator.apache.org>
> Date: Tuesday, September 26, 2017 at 6:30 PM
> To: "dev@trafficcontrol.incubator.apache.org" <de...@trafficcontrol.incubator.apache.org>
> Subject: Re: Apache Cwiki vs. Github Wiki vs. Github Docs
>
> If having the Github wiki populated is a desire. You could publish the mb,
> rst, etc docs, already being worked on given Ryan's statement, via github's
> wiki repo methodology.
> https://help.github.com/articles/adding-and-editing-wiki-pages-locally/
>
> On Tue, Sep 26, 2017 at 5:48 PM, Dave Neuman <ne...@apache.org>> wrote:
>
> I agree with Jan. I don't see what moving to github wiki really does for
> us that cwiki can't, as a matter of fact it will probably cause other
> issues like only committers can edit it. I also agree that we should have
> better and more formal docs; especially ones that help new users get ATC
> installed quickly.
>
>
>
> On Tue, Sep 26, 2017 at 17:10 Jan van Doorn <jv...@knutsel.com>> wrote:
>
>> I think we still need a place to document things like meet ups and the
>> likes? I like the “less formal” feel of a wiki, and think the docs should
>> be more “official”, and part of the release.
>>
>> Some people have started putting documentation in the README.md with the
>> code, and while I think that’s better than no documentation, I think a
>> project like ours should have official user and admin guides as part of
> the
>> release. We have been letting that part slip a little bit, but just
> giving
>> up on it seems too easy for me…
>>
>> So I don’t like 1. Or 1. :-) I think we should stay on the apache Cwiki
>> for informal notes and beef up our rst docs for admins and users.
>>
>> Rgds,
>> JvD
>>
>>
>>> On Sep 26, 2017, at 2:56 PM, Durfey, Ryan <Ry...@comcast.com>>
>> wrote:
>>>
>>> All,
>>>
>>> Given the move to Github, I think we should consider moving out of
>> Apache Cwiki. While I think this is a far superior wiki to the offering
>> from Github, I think unifying everything in one environment is a better
>> overall approach. I also wanted to consider foregoing the wiki
> altogether
>> and suggest pushing this documentation into a new “beta” or “design”
>> section under our docs in
>> http://trafficcontrol.apache.org/docs/latest/index.html . This would
>> unify us into a single documentation format, simplify the transition from
>> design to publication, and eliminate the need to support a wiki
> altogether.
>>>
>>> Would love feedback on this:
>>>
>>> 1. Move to Github wiki
>>>
>>> Or
>>>
>>> 1. Move to a new “beta” section under
>> http://trafficcontrol.apache.org/docs/latest/index.html
>>>
>>> Ryan Durfey
>>> Sr. Product Manager - CDN | Comcast Technology Solutions
>>> 1899 Wynkoop Ste. 550 | Denver, CO 80202
>>> M | 303-524-5099
>>> ryan_durfey@comcast.com<ma...@comcast.com>
>>> CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com><mailto:
>> cdn_support@comcast.com<ma...@comcast.com>>
>>>
>>
>>
>
>
Re: Apache Cwiki vs. Github Wiki vs. Github Docs
Posted by "Durfey, Ryan" <Ry...@comcast.com>.
And per Nick’s feedback I think most users would be able to submit PRs for document modifications which would need to be accepted by committers. I think that solves the access issue.
The logic of the move from jira to github was to simplify/unify everything to make it so there was less need for system access and less overhead of maintaining multiple sites. In moving to “full” github, everything collapses down into one single system and we can focus on keeping it up to date. It also forces us to use the github publishing system more regularly which should improve documentation output. I think we could still keep informal information in the site we would just create a new section for it that calls out what it is.
If it makes a difference, Ashish and I could port the documentation over to either location so the lift on the developers would be nil aside from feedback.
Ryan Durfey M | 303-524-5099
CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com>
From: <ne...@gmail.com> on behalf of NerdyNick <ne...@apache.org>
Reply-To: "dev@trafficcontrol.incubator.apache.org" <de...@trafficcontrol.incubator.apache.org>
Date: Tuesday, September 26, 2017 at 6:30 PM
To: "dev@trafficcontrol.incubator.apache.org" <de...@trafficcontrol.incubator.apache.org>
Subject: Re: Apache Cwiki vs. Github Wiki vs. Github Docs
If having the Github wiki populated is a desire. You could publish the mb,
rst, etc docs, already being worked on given Ryan's statement, via github's
wiki repo methodology.
https://help.github.com/articles/adding-and-editing-wiki-pages-locally/
On Tue, Sep 26, 2017 at 5:48 PM, Dave Neuman <ne...@apache.org>> wrote:
I agree with Jan. I don't see what moving to github wiki really does for
us that cwiki can't, as a matter of fact it will probably cause other
issues like only committers can edit it. I also agree that we should have
better and more formal docs; especially ones that help new users get ATC
installed quickly.
On Tue, Sep 26, 2017 at 17:10 Jan van Doorn <jv...@knutsel.com>> wrote:
> I think we still need a place to document things like meet ups and the
> likes? I like the “less formal” feel of a wiki, and think the docs should
> be more “official”, and part of the release.
>
> Some people have started putting documentation in the README.md with the
> code, and while I think that’s better than no documentation, I think a
> project like ours should have official user and admin guides as part of
the
> release. We have been letting that part slip a little bit, but just
giving
> up on it seems too easy for me…
>
> So I don’t like 1. Or 1. :-) I think we should stay on the apache Cwiki
> for informal notes and beef up our rst docs for admins and users.
>
> Rgds,
> JvD
>
>
> > On Sep 26, 2017, at 2:56 PM, Durfey, Ryan <Ry...@comcast.com>>
> wrote:
> >
> > All,
> >
> > Given the move to Github, I think we should consider moving out of
> Apache Cwiki. While I think this is a far superior wiki to the offering
> from Github, I think unifying everything in one environment is a better
> overall approach. I also wanted to consider foregoing the wiki
altogether
> and suggest pushing this documentation into a new “beta” or “design”
> section under our docs in
> http://trafficcontrol.apache.org/docs/latest/index.html . This would
> unify us into a single documentation format, simplify the transition from
> design to publication, and eliminate the need to support a wiki
altogether.
> >
> > Would love feedback on this:
> >
> > 1. Move to Github wiki
> >
> > Or
> >
> > 1. Move to a new “beta” section under
> http://trafficcontrol.apache.org/docs/latest/index.html
> >
> > Ryan Durfey
> > Sr. Product Manager - CDN | Comcast Technology Solutions
> > 1899 Wynkoop Ste. 550 | Denver, CO 80202
> > M | 303-524-5099
> > ryan_durfey@comcast.com<ma...@comcast.com>
> > CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com><mailto:
> cdn_support@comcast.com<ma...@comcast.com>>
> >
>
>
Re: Apache Cwiki vs. Github Wiki vs. Github Docs
Posted by NerdyNick <ne...@apache.org>.
If having the Github wiki populated is a desire. You could publish the mb,
rst, etc docs, already being worked on given Ryan's statement, via github's
wiki repo methodology.
https://help.github.com/articles/adding-and-editing-wiki-pages-locally/
On Tue, Sep 26, 2017 at 5:48 PM, Dave Neuman <ne...@apache.org> wrote:
> I agree with Jan. I don't see what moving to github wiki really does for
> us that cwiki can't, as a matter of fact it will probably cause other
> issues like only committers can edit it. I also agree that we should have
> better and more formal docs; especially ones that help new users get ATC
> installed quickly.
>
>
>
> On Tue, Sep 26, 2017 at 17:10 Jan van Doorn <jv...@knutsel.com> wrote:
>
> > I think we still need a place to document things like meet ups and the
> > likes? I like the “less formal” feel of a wiki, and think the docs should
> > be more “official”, and part of the release.
> >
> > Some people have started putting documentation in the README.md with the
> > code, and while I think that’s better than no documentation, I think a
> > project like ours should have official user and admin guides as part of
> the
> > release. We have been letting that part slip a little bit, but just
> giving
> > up on it seems too easy for me…
> >
> > So I don’t like 1. Or 1. :-) I think we should stay on the apache Cwiki
> > for informal notes and beef up our rst docs for admins and users.
> >
> > Rgds,
> > JvD
> >
> >
> > > On Sep 26, 2017, at 2:56 PM, Durfey, Ryan <Ry...@comcast.com>
> > wrote:
> > >
> > > All,
> > >
> > > Given the move to Github, I think we should consider moving out of
> > Apache Cwiki. While I think this is a far superior wiki to the offering
> > from Github, I think unifying everything in one environment is a better
> > overall approach. I also wanted to consider foregoing the wiki
> altogether
> > and suggest pushing this documentation into a new “beta” or “design”
> > section under our docs in
> > http://trafficcontrol.apache.org/docs/latest/index.html . This would
> > unify us into a single documentation format, simplify the transition from
> > design to publication, and eliminate the need to support a wiki
> altogether.
> > >
> > > Would love feedback on this:
> > >
> > > 1. Move to Github wiki
> > >
> > > Or
> > >
> > > 1. Move to a new “beta” section under
> > http://trafficcontrol.apache.org/docs/latest/index.html
> > >
> > > Ryan Durfey
> > > Sr. Product Manager - CDN | Comcast Technology Solutions
> > > 1899 Wynkoop Ste. 550 | Denver, CO 80202
> > > M | 303-524-5099
> > > ryan_durfey@comcast.com<ma...@comcast.com>
> > > CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<mailto:
> > cdn_support@comcast.com>
> > >
> >
> >
>
Re: Apache Cwiki vs. Github Wiki vs. Github Docs
Posted by Dave Neuman <ne...@apache.org>.
I agree with Jan. I don't see what moving to github wiki really does for
us that cwiki can't, as a matter of fact it will probably cause other
issues like only committers can edit it. I also agree that we should have
better and more formal docs; especially ones that help new users get ATC
installed quickly.
On Tue, Sep 26, 2017 at 17:10 Jan van Doorn <jv...@knutsel.com> wrote:
> I think we still need a place to document things like meet ups and the
> likes? I like the “less formal” feel of a wiki, and think the docs should
> be more “official”, and part of the release.
>
> Some people have started putting documentation in the README.md with the
> code, and while I think that’s better than no documentation, I think a
> project like ours should have official user and admin guides as part of the
> release. We have been letting that part slip a little bit, but just giving
> up on it seems too easy for me…
>
> So I don’t like 1. Or 1. :-) I think we should stay on the apache Cwiki
> for informal notes and beef up our rst docs for admins and users.
>
> Rgds,
> JvD
>
>
> > On Sep 26, 2017, at 2:56 PM, Durfey, Ryan <Ry...@comcast.com>
> wrote:
> >
> > All,
> >
> > Given the move to Github, I think we should consider moving out of
> Apache Cwiki. While I think this is a far superior wiki to the offering
> from Github, I think unifying everything in one environment is a better
> overall approach. I also wanted to consider foregoing the wiki altogether
> and suggest pushing this documentation into a new “beta” or “design”
> section under our docs in
> http://trafficcontrol.apache.org/docs/latest/index.html . This would
> unify us into a single documentation format, simplify the transition from
> design to publication, and eliminate the need to support a wiki altogether.
> >
> > Would love feedback on this:
> >
> > 1. Move to Github wiki
> >
> > Or
> >
> > 1. Move to a new “beta” section under
> http://trafficcontrol.apache.org/docs/latest/index.html
> >
> > Ryan Durfey
> > Sr. Product Manager - CDN | Comcast Technology Solutions
> > 1899 Wynkoop Ste. 550 | Denver, CO 80202
> > M | 303-524-5099
> > ryan_durfey@comcast.com<ma...@comcast.com>
> > CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<mailto:
> cdn_support@comcast.com>
> >
>
>
Re: Apache Cwiki vs. Github Wiki vs. Github Docs
Posted by Jan van Doorn <jv...@knutsel.com>.
I think we still need a place to document things like meet ups and the likes? I like the “less formal” feel of a wiki, and think the docs should be more “official”, and part of the release.
Some people have started putting documentation in the README.md with the code, and while I think that’s better than no documentation, I think a project like ours should have official user and admin guides as part of the release. We have been letting that part slip a little bit, but just giving up on it seems too easy for me…
So I don’t like 1. Or 1. :-) I think we should stay on the apache Cwiki for informal notes and beef up our rst docs for admins and users.
Rgds,
JvD
> On Sep 26, 2017, at 2:56 PM, Durfey, Ryan <Ry...@comcast.com> wrote:
>
> All,
>
> Given the move to Github, I think we should consider moving out of Apache Cwiki. While I think this is a far superior wiki to the offering from Github, I think unifying everything in one environment is a better overall approach. I also wanted to consider foregoing the wiki altogether and suggest pushing this documentation into a new “beta” or “design” section under our docs in http://trafficcontrol.apache.org/docs/latest/index.html . This would unify us into a single documentation format, simplify the transition from design to publication, and eliminate the need to support a wiki altogether.
>
> Would love feedback on this:
>
> 1. Move to Github wiki
>
> Or
>
> 1. Move to a new “beta” section under http://trafficcontrol.apache.org/docs/latest/index.html
>
> Ryan Durfey
> Sr. Product Manager - CDN | Comcast Technology Solutions
> 1899 Wynkoop Ste. 550 | Denver, CO 80202
> M | 303-524-5099
> ryan_durfey@comcast.com<ma...@comcast.com>
> CDN Support (24x7): 866-405-2993 or cdn_support@comcast.com<ma...@comcast.com>
>