Re: [EXTERNAL] Re: The purpose, structure, and future of the ATC Confluence Wiki

["Gray, Jonathan" <Jo...@comcast.com.INVALID>]

A lot of it also is who your audience is and what they need to do.  Confluence is a powerful wiki engine with capabilities that far exceed that of GHW with an easier, but not just pure markdown, UI to me at least.  If the only contributors won’t use those capabilities and only use what’s available via markdown and file attachments, it’s a bit of a wash I think.  It’s not something we use daily or as part of normal workflows anymore except for the working group minutes (which we’re trying to change now it sounds like) and presentations.  If someone is passionate about it, that’s fine though.

Jonathan G

From: ocket 8888 <oc...@gmail.com>
Date: Tuesday, August 24, 2021 at 1:27 PM
To: dev@trafficcontrol.apache.org <de...@trafficcontrol.apache.org>
Subject: [EXTERNAL] Re: The purpose, structure, and future of the ATC Confluence Wiki
The GH wiki is, under the hood, a git repo, so you can add whatever files
you want, including pdfs and whathaveyou. If there are videos we might need
git-LFS, but it should be totally doable.

On Tue, Aug 24, 2021 at 1:16 PM Dave Neuman <ne...@apache.org> wrote:

> We used cwiki because GH wiki did not exist at the time.
> I personally get the most value from the presentations that we have on our
> wiki.  As long as we move those to GH wiki, I have no problem moving off of
> cwiki.
> We need to make sure we update our webpage (trafficcontrol.apache.org) and
> docs as well.
>
>
>
> On Tue, Aug 24, 2021 at 12:54 PM ocket 8888 <oc...@gmail.com> wrote:
>
> > There are a lot of pages on the ATC Confluence wiki, many of which no
> > longer appear to serve any purpose (e.g. Traffic Analytics) and/or have
> > been superseded by blueprints (e.g. Specs/Layered Profiles). With the
> > recent decision of the TC working group to host the meeting notes and
> > agenda on the mailing list, the only parts of the wiki that are regularly
> > updated won't be anymore.
> >
> > With that in mind, we discussed cleaning up the wiki by removing some
> > outdated pages, moving feature definitions to blueprints (or removing
> said
> > pages in favor of existing blueprints), and at a certain point we
> wondered
> > what the purpose of Confluence even was anymore. There are pages there
> that
> > aren't captured anywhere else and have good information, but they're not
> in
> > the repository with the code, contribution guidelines, and documentation
> -
> > but they could be.
> >
> > What if instead of using Confluence at all, we just switched to a GitHub
> > wiki? That would allow non-committers to suggest edits (or even just make
> > edits, depending on our settings), and in the porting process we could
> > tease out the things that work better in other places (e.g.
> documentation,
> > blueprints, etc.) and be left with a solid, small set of information
> that's
> > easier to maintain, navigate, and hopefully read.
> >
> > Confluence is also somewhat frustrating to work with, especially for
> > developers who are used to writing their documents in markup (which is
> what
> > GitHub's wikis use, specifically Markdown) but on Confluence instead have
> > to use a rich text editor with some annoying restrictions on nested
> > formatting and the like, and is missing some features like code
> > highlighting.
> >
> > For this thread I'd like to just focus on that idea of using the GH wiki
> > system; for actually cleaning up pages we'd probably want to do a PR and
> > then bring that back to the list so that when discussing it we could
> > actually see that the information was getting properly transferred
> > accurately and in its entirety.
> >
>

Re: [EXTERNAL] Re: The purpose, structure, and future of the ATC Confluence Wiki

[Zach Hoffman <zr...@apache.org>]

> Confluence is a powerful wiki engine with capabilities that far exceed
that of GHW with an easier, but not just pure markdown, UI to me at least.

To me, the main value of Confluence is its WYSIWYG editing. The GitHub
Writer browser extension lets you use a WYSIWYG editor on GitHub Wiki:
https://ckeditor.com/github-writer

GitHub Writer should also make migration to the GH wiki way easier, as you
can just select all -> copy the confluence page -> paste into the GH wiki.

-Zach

On Tue, Aug 24, 2021 at 1:42 PM Gray, Jonathan
<Jo...@comcast.com.invalid> wrote:

> A lot of it also is who your audience is and what they need to do.
> Confluence is a powerful wiki engine with capabilities that far exceed that
> of GHW with an easier, but not just pure markdown, UI to me at least.  If
> the only contributors won’t use those capabilities and only use what’s
> available via markdown and file attachments, it’s a bit of a wash I think.
> It’s not something we use daily or as part of normal workflows anymore
> except for the working group minutes (which we’re trying to change now it
> sounds like) and presentations.  If someone is passionate about it, that’s
> fine though.
>
> Jonathan G
>
> From: ocket 8888 <oc...@gmail.com>
> Date: Tuesday, August 24, 2021 at 1:27 PM
> To: dev@trafficcontrol.apache.org <de...@trafficcontrol.apache.org>
> Subject: [EXTERNAL] Re: The purpose, structure, and future of the ATC
> Confluence Wiki
> The GH wiki is, under the hood, a git repo, so you can add whatever files
> you want, including pdfs and whathaveyou. If there are videos we might need
> git-LFS, but it should be totally doable.
>
> On Tue, Aug 24, 2021 at 1:16 PM Dave Neuman <ne...@apache.org> wrote:
>
> > We used cwiki because GH wiki did not exist at the time.
> > I personally get the most value from the presentations that we have on
> our
> > wiki.  As long as we move those to GH wiki, I have no problem moving off
> of
> > cwiki.
> > We need to make sure we update our webpage (trafficcontrol.apache.org)
> and
> > docs as well.
> >
> >
> >
> > On Tue, Aug 24, 2021 at 12:54 PM ocket 8888 <oc...@gmail.com> wrote:
> >
> > > There are a lot of pages on the ATC Confluence wiki, many of which no
> > > longer appear to serve any purpose (e.g. Traffic Analytics) and/or have
> > > been superseded by blueprints (e.g. Specs/Layered Profiles). With the
> > > recent decision of the TC working group to host the meeting notes and
> > > agenda on the mailing list, the only parts of the wiki that are
> regularly
> > > updated won't be anymore.
> > >
> > > With that in mind, we discussed cleaning up the wiki by removing some
> > > outdated pages, moving feature definitions to blueprints (or removing
> > said
> > > pages in favor of existing blueprints), and at a certain point we
> > wondered
> > > what the purpose of Confluence even was anymore. There are pages there
> > that
> > > aren't captured anywhere else and have good information, but they're
> not
> > in
> > > the repository with the code, contribution guidelines, and
> documentation
> > -
> > > but they could be.
> > >
> > > What if instead of using Confluence at all, we just switched to a
> GitHub
> > > wiki? That would allow non-committers to suggest edits (or even just
> make
> > > edits, depending on our settings), and in the porting process we could
> > > tease out the things that work better in other places (e.g.
> > documentation,
> > > blueprints, etc.) and be left with a solid, small set of information
> > that's
> > > easier to maintain, navigate, and hopefully read.
> > >
> > > Confluence is also somewhat frustrating to work with, especially for
> > > developers who are used to writing their documents in markup (which is
> > what
> > > GitHub's wikis use, specifically Markdown) but on Confluence instead
> have
> > > to use a rich text editor with some annoying restrictions on nested
> > > formatting and the like, and is missing some features like code
> > > highlighting.
> > >
> > > For this thread I'd like to just focus on that idea of using the GH
> wiki
> > > system; for actually cleaning up pages we'd probably want to do a PR
> and
> > > then bring that back to the list so that when discussing it we could
> > > actually see that the information was getting properly transferred
> > > accurately and in its entirety.
> > >
> >
>