You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beam.apache.org by Hadar Hod <ha...@google.com.INVALID> on 2016/11/04 02:42:30 UTC
Contributing to Beam docs
Hi Beamers!
I'm Hadar. I've worked on Dataflow documentation in the past, and have
recently started contributing to the Beam docs. I'm excited to work with
all of you and to be a part of this project. :)
I believe the current structure of the website can be improved, so I'd like
to propose a slightly different one. On a high level, I propose changing
the tabs in the top menu and reorganizing some of the docs. Instead of the
current "Use", "Learn", "Contribute", "Blog", and "Project" tabs, we could
have "Get Started", "Documentation", "Contribute", and "Blog".
I applied this new structure in a pull request
<https://github.com/apache/incubator-beam-site/pull/62>, which is staged
here
<http://apache-beam-website-pull-requests.storage.googleapis.com/62/index.html>.
If you've worked on the website before, you've probably run into this -
note that you'll have to append "/index.html" to each URL.
Thoughts? Thanks!
Hadar
Re: Contributing to Beam docs
Posted by Hadar Hod <ha...@google.com.INVALID>.
Thanks for your feedback, everyone! I've incorporated some of the changes
you suggested. See the new version staged here
<http://apache-beam-website-pull-requests.storage.googleapis.com/62/index.html>
.
On Fri, Nov 4, 2016 at 10:54 AM, Davor Bonaci <da...@google.com.invalid>
wrote:
> >
> > From the URL Hadar shared, I believe we are using GCS buckets to host the
> > content. https://cloud.google.com/storage/docs/hosting-static-website
> has
> > information about hosting static websites. Have we looked at that before?
> > There's a section of that titled "Optional: Assigning pages" which has
> more
> > information about editing website configuration. (you may need to change
> > some config settings so that GCS knows it's a website before it'll give
> you
> > those options)
> >
> > > p.s. I'd love to contribute to solving the /index.html thing. Seems
> like
> > > something we should be able to engineer our way around.
> >
>
> I have experimented with automatic staging of website pull requests to
> simplify reviews -- it is a work-in-progress due to the "/index.html
> thing".
>
> In the current setup, we'd need a (sub-)domain with CNAME and a TXT entries
> to solve the problem. I've floated the idea with Infra -- they weren't
> enthusiastic about doing this as a subdomain of beam.incubator.apache.org.
> Unless we choose to obtain another domain elsewhere, the only option I'm
> aware of would be to try to "sed" the jekyll's output to fix the links --
> somewhat fragile and non-great, but possible.
>
Re: Contributing to Beam docs
Posted by Davor Bonaci <da...@google.com.INVALID>.
>
> From the URL Hadar shared, I believe we are using GCS buckets to host the
> content. https://cloud.google.com/storage/docs/hosting-static-website has
> information about hosting static websites. Have we looked at that before?
> There's a section of that titled "Optional: Assigning pages" which has more
> information about editing website configuration. (you may need to change
> some config settings so that GCS knows it's a website before it'll give you
> those options)
>
> > p.s. I'd love to contribute to solving the /index.html thing. Seems like
> > something we should be able to engineer our way around.
>
I have experimented with automatic staging of website pull requests to
simplify reviews -- it is a work-in-progress due to the "/index.html thing".
In the current setup, we'd need a (sub-)domain with CNAME and a TXT entries
to solve the problem. I've floated the idea with Infra -- they weren't
enthusiastic about doing this as a subdomain of beam.incubator.apache.org.
Unless we choose to obtain another domain elsewhere, the only option I'm
aware of would be to try to "sed" the jekyll's output to fix the links --
somewhat fragile and non-great, but possible.
Re: Contributing to Beam docs
Posted by Stephen Sisk <si...@google.com.INVALID>.
hi!
From the URL Hadar shared, I believe we are using GCS buckets to host the
content. https://cloud.google.com/storage/docs/hosting-static-website has
information about hosting static websites. Have we looked at that before?
There's a section of that titled "Optional: Assigning pages" which has more
information about editing website configuration. (you may need to change
some config settings so that GCS knows it's a website before it'll give you
those options)
Stephen
On Thu, Nov 3, 2016 at 8:16 PM Kenneth Knowles <kl...@google.com.invalid>
wrote:
> This is great. These menus seem really intuitive for finding what you need.
> I especially like the clarity in Get Started and Documentation. A pretty
> big challenge, since we have <n> runners and <m> SDKs that all need to be
> called out prominently in order to let users know what Beam is about.
>
> I had ~3 thoughts.
>
> 1. "Get Started > Support " contains mostly things that I associate with
> "Community". I would say only the users@ mailing list, StackOverflow, and
> to a lesser extent JIRA are user facing, while the rest is contributor
> facing.
>
> 2. "Contribute > Work In Progress" I wasn't quite sure how to interpret
> until I clicked in on it. I favor slightly florid vocabulary like "Ongoing
> Endeavors" but maybe there is a middle ground?
>
> 3. The organization of the Contribute subsections seems like it could put
> together three sections for guides, miscellany, and promotion.
>
> Contribute >
> Get Started Contributing (was "Contributor Hub", should have the
> "starter" content from Work In Progress page)
> ----------------
> Contribution Guide
> Testing Guide (was "Testing")
> Release Guide
> --------------
> Team
> Technical Vision (optional, from "Contributor Hub")
> Design Principles
> Ongoing Endeavors (was "Work In Progress")
> Source Repository
> Issue Tracking (was "Support" elsewhere)
> Mailing Lists, etc (include Slack and dev@/commits@ lists)
> --------------
> Presentation Materials (was "Talks" but "Talks" sounds like prerecorded
> learning material)
> Logos and Design
>
> Kenn
>
> p.s. I'd love to contribute to solving the /index.html thing. Seems like
> something we should be able to engineer our way around.
>
> On Thu, Nov 3, 2016 at 7:42 PM Hadar Hod <ha...@google.com.invalid>
> wrote:
>
> > Hi Beamers!
> >
> > I'm Hadar. I've worked on Dataflow documentation in the past, and have
> > recently started contributing to the Beam docs. I'm excited to work with
> > all of you and to be a part of this project. :)
> >
> > I believe the current structure of the website can be improved, so I'd
> like
> > to propose a slightly different one. On a high level, I propose changing
> > the tabs in the top menu and reorganizing some of the docs. Instead of
> the
> > current "Use", "Learn", "Contribute", "Blog", and "Project" tabs, we
> could
> > have "Get Started", "Documentation", "Contribute", and "Blog".
> >
> > I applied this new structure in a pull request
> > <https://github.com/apache/incubator-beam-site/pull/62>, which is staged
> > here
> > <
> >
> http://apache-beam-website-pull-requests.storage.googleapis.com/62/index.html
> > >.
> > If you've worked on the website before, you've probably run into this -
> > note that you'll have to append "/index.html" to each URL.
> >
> > Thoughts? Thanks!
> >
> > Hadar
> >
>
Re: Contributing to Beam docs
Posted by Kenneth Knowles <kl...@google.com.INVALID>.
This is great. These menus seem really intuitive for finding what you need.
I especially like the clarity in Get Started and Documentation. A pretty
big challenge, since we have <n> runners and <m> SDKs that all need to be
called out prominently in order to let users know what Beam is about.
I had ~3 thoughts.
1. "Get Started > Support " contains mostly things that I associate with
"Community". I would say only the users@ mailing list, StackOverflow, and
to a lesser extent JIRA are user facing, while the rest is contributor
facing.
2. "Contribute > Work In Progress" I wasn't quite sure how to interpret
until I clicked in on it. I favor slightly florid vocabulary like "Ongoing
Endeavors" but maybe there is a middle ground?
3. The organization of the Contribute subsections seems like it could put
together three sections for guides, miscellany, and promotion.
Contribute >
Get Started Contributing (was "Contributor Hub", should have the
"starter" content from Work In Progress page)
----------------
Contribution Guide
Testing Guide (was "Testing")
Release Guide
--------------
Team
Technical Vision (optional, from "Contributor Hub")
Design Principles
Ongoing Endeavors (was "Work In Progress")
Source Repository
Issue Tracking (was "Support" elsewhere)
Mailing Lists, etc (include Slack and dev@/commits@ lists)
--------------
Presentation Materials (was "Talks" but "Talks" sounds like prerecorded
learning material)
Logos and Design
Kenn
p.s. I'd love to contribute to solving the /index.html thing. Seems like
something we should be able to engineer our way around.
On Thu, Nov 3, 2016 at 7:42 PM Hadar Hod <ha...@google.com.invalid> wrote:
> Hi Beamers!
>
> I'm Hadar. I've worked on Dataflow documentation in the past, and have
> recently started contributing to the Beam docs. I'm excited to work with
> all of you and to be a part of this project. :)
>
> I believe the current structure of the website can be improved, so I'd like
> to propose a slightly different one. On a high level, I propose changing
> the tabs in the top menu and reorganizing some of the docs. Instead of the
> current "Use", "Learn", "Contribute", "Blog", and "Project" tabs, we could
> have "Get Started", "Documentation", "Contribute", and "Blog".
>
> I applied this new structure in a pull request
> <https://github.com/apache/incubator-beam-site/pull/62>, which is staged
> here
> <
> http://apache-beam-website-pull-requests.storage.googleapis.com/62/index.html
> >.
> If you've worked on the website before, you've probably run into this -
> note that you'll have to append "/index.html" to each URL.
>
> Thoughts? Thanks!
>
> Hadar
>
Re: Contributing to Beam docs
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Thanks Hadar,
it looks better for me !
Just a small comment: I think we need to give more visibility to what is
provided by Beam: SDKs/DSLs, I/Os, Runners.
It's one of my intention in the new skin proposal PR
(https://github.com/apache/incubator-beam-site/pull/64) in the Learn and
Overview sections.
Something like what we have in Apache Camel for the components (likely
equivalent to Beam I/Os) would help users IMHO.
Thanks again and welcome aboard !
Regards
JB
On 11/04/2016 03:42 AM, Hadar Hod wrote:
> Hi Beamers!
>
> I'm Hadar. I've worked on Dataflow documentation in the past, and have
> recently started contributing to the Beam docs. I'm excited to work with
> all of you and to be a part of this project. :)
>
> I believe the current structure of the website can be improved, so I'd like
> to propose a slightly different one. On a high level, I propose changing
> the tabs in the top menu and reorganizing some of the docs. Instead of the
> current "Use", "Learn", "Contribute", "Blog", and "Project" tabs, we could
> have "Get Started", "Documentation", "Contribute", and "Blog".
>
> I applied this new structure in a pull request
> <https://github.com/apache/incubator-beam-site/pull/62>, which is staged
> here
> <http://apache-beam-website-pull-requests.storage.googleapis.com/62/index.html>.
> If you've worked on the website before, you've probably run into this -
> note that you'll have to append "/index.html" to each URL.
>
> Thoughts? Thanks!
>
> Hadar
>
--
Jean-Baptiste Onofr�
jbonofre@apache.org
http://blog.nanthrax.net
Talend - http://www.talend.com