[prev in list] [next in list] [prev in thread] [next in thread]
List: avro-user
Subject: Re: New website
From: Martin Grigorov <mgrigorov () apache ! org>
Date: 2021-12-13 11:51:55
Message-ID: CAMomwMqFS2vrZcHi4iMsG0WvRvvYLg0BEaVix15wEQWu9Y42yQ () mail ! gmail ! com
[Download RAW message or body]
On Mon, Dec 13, 2021 at 9:38 AM Martin Grigorov <mgrigorov@apache.org>
wrote:
> Hi Ryan,
>
> On Sun, Dec 12, 2021 at 1:36 PM Ryan Skraba <ryan@skraba.com> wrote:
>
>> Hello!
>>
>> I realized that I haven't commented on this mailing list thread -- I
>> made some comments on https://issues.apache.org/jira/browse/AVRO-2175
>>
>> This looks amazing and we should merge it very soon :D It's not
>> perfect, but it's really a great improvement and definitely not worst
>> than the existing website!
>>
>> I've been taking a look at what we need to use the existing
>> infrastructure, and there's interesting links at:
>>
>> - https://infra.apache.org/release-download-pages.html
>> -
>> https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+featur=
es
>> - https://infra.apache.org/website-guidelines.html
>> - https://infra.apache.org/project-site.html
>>
>> I like that Beam has the website in the main repo, but notably the
>> INFRA recommendation is that we use a separate repo for the website
>> (named `avro-site` though). Any thoughts? It's always something we
>> can try and change later! Would it make it easier for the javadoc and
>> other languages if they were in the same repo, or does it make little
>> difference?
>>
>
> Since some docs are generated by other tools (C/C++/C#) and they need to
> be copied to the rest of the website I agree that it would be easier if t=
he
> website is in the main repo!
> Also any changes to the spec/IDL will be in one PR (same repo) instead of
> two (main+website).
>
>
>>
>> The old site actually contains all of the documentation for EVERY
>> release, which can be found here:
>>
>> - https://svn.apache.org/repos/asf/avro/site/publish/docs/
>> - https://avro.apache.org/docs/
>>
>> Would it be tricky to adjust your work to mirror the existing
>> structure for existing docs? I'm not even too fussy about not
>> breaking the links in /docs/current/ but all of the existing pages
>> such as /docs/1.7.7/ should be maintained if possible!
>>
>
> I could make the "Documention" nav tab into a dropdown with menu items,
> one for each version.
> 1.11.0 and 1.10.2, and any future release, will be proper Markdown
> documents. The menu items for all previous versions will be links to the
> respective folder at https://avro.apache.org/docs/.
>
Done!
https://avro-website.netlify.app/
> If someone wants to migrate some more old docs to Markdown then please
> fork the repo and send a PR!
>
>
>>
>> There's so many good suggestions here for future work and improving
>> our message and communication, I created
>> https://issues.apache.org/jira/browse/AVRO-3264 to point to this
>> discussion after we get this up.
>>
>> Thanks again for your great work!
>>
>> Ryan
>>
>> On Thu, Nov 4, 2021 at 4:26 PM Lee Hambley <lee.hambley@gmail.com> wrote=
:
>> >
>> > I speak only for myself, but I am working in an environment where I am
>> regularly checking docs all the way back to 1.8.x because we have legacy
>> systems we cannot upgrade, and I am often referencing rules about schema
>> canonical form. I value a lot the sidebar bottom version switching
>> navigation from sites such as here
>> https://fastavro.readthedocs.io/en/latest/writer.html#using-the-record-h=
int-to-specify-which-branch-of-a-union-to-take
>> ... but I know it can be extraordinarily difficult to make it work
>> correctly with these static site generators.
>> >
>> > Lee Hambley
>> > http://lee.hambley.name/
>> > +49 (0) 170 298 5667
>> >
>> >
>> > On Thu, 4 Nov 2021 at 16:23, Martin Grigorov <mgrigorov@apache.org>
>> wrote:
>> >>
>> >>
>> >>
>> >> On Thu, Nov 4, 2021 at 5:04 PM Isma=C3=ABl Mej=C3=ADa <iemejia@gmail.=
com> wrote:
>> >>>
>> >>> Wow this is pretty neat ! Nice job Martin! A modern website can
>> >>> encourage more contributions.
>> >>> I am more interested on content than aesthetics first. Is everything
>> >>> already migrated? Anything missing? Any issue to report?
>> >>
>> >>
>> >> Everything is migrated for the documentation of the *current* version=
.
>> >> The old site contains documentation for both current and current-1. I=
s
>> this something you would like to preserve ?
>> >>
>> >>>
>> >>>
>> >>>
>> >>> On Tue, Nov 2, 2021 at 7:01 PM Martin Grigorov <mgrigorov@apache.org=
>
>> wrote:
>> >>> >
>> >>> > Hi,
>> >>> >
>> >>> > Anyone willing to send a PR with the suggested improvement?
>> >>> > Or at least open an issue with the well formulated text and I will
>> add it!
>> >>> >
>> >>> > Regards,
>> >>> > Martin
>> >>> >
>> >>> > On Tue, Nov 2, 2021, 18:08 Oscar Westra van Holthe - Kind <
>> oscar@westravanholthe.nl> wrote:
>> >>> >>
>> >>> >> Hi,
>> >>> >>
>> >>> >> This is a huge improvement. Responsive, excellent navigation,
>> syntax
>> >>> >> highlighting, ...
>> >>> >>
>> >>> >> The only downside I see was already mentioned by Lee: the landing
>> page is
>> >>> >> too empty (also in a mobile browser).
>> >>> >> I think we could really benefit from mentioning the unique sellin=
g
>> point of
>> >>> >> Avro here: "Your Data. Any Time, Anywhere." And then mention the
>> language
>> >>> >> availability & excellent schema evolution.
>> >>> >>
>> >>> >> Kind regards,
>> >>> >> Oscar
>> >>> >>
>> >>> >> On Thu, 28 Oct 2021 at 10:43, Martin Grigorov <
>> mgrigorov@apache.org> wrote:
>> >>> >>
>> >>> >> > Hi all,
>> >>> >> >
>> >>> >> > Please check the new candidate for Apache Avro website:
>> >>> >> > https://avro-website.netlify.app/
>> >>> >> >
>> >>> >> > It is based on Hugo and uses Docsy theme.
>> >>> >> > Its source code and instructions how to build could be found at
>> >>> >> > https://github.com/martin-g/avro-website.
>> >>> >> > The JIRA ticket is:
>> https://issues.apache.org/jira/browse/AVRO-2175
>> >>> >> >
>> >>> >> > I am not web designer, so some things may look not finished.
>> >>> >> > I've just copied the HTML content from the old site (
>> >>> >> > https://avro.apache.org/) and converted it to Markdown for Hugo=
.
>> >>> >> >
>> >>> >> > Any feedback is welcome! With Pull Requests would be awesome!
>> >>> >> >
>> >>> >> > Regards,
>> >>> >> > Martin
>> >>> >> >
>>
>
[Attachment #3 (text/html)]
<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" \
class="gmail_attr">On Mon, Dec 13, 2021 at 9:38 AM Martin Grigorov <<a \
href="mailto:mgrigorov@apache.org">mgrigorov@apache.org</a>> \
wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div \
dir="ltr">Hi Ryan,</div><br><div class="gmail_quote"><div dir="ltr" \
class="gmail_attr">On Sun, Dec 12, 2021 at 1:36 PM Ryan Skraba <<a \
href="mailto:ryan@skraba.com" target="_blank">ryan@skraba.com</a>> \
wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello!<br> <br>
I realized that I haven't commented on this mailing list thread -- I<br>
made some comments on <a href="https://issues.apache.org/jira/browse/AVRO-2175" \
rel="noreferrer" target="_blank">https://issues.apache.org/jira/browse/AVRO-2175</a><br>
<br>
This looks amazing and we should merge it very soon :D It's not<br>
perfect, but it's really a great improvement and definitely not worst<br>
than the existing website!<br>
<br>
I've been taking a look at what we need to use the existing<br>
infrastructure, and there's interesting links at:<br>
<br>
- <a href="https://infra.apache.org/release-download-pages.html" rel="noreferrer" \
target="_blank">https://infra.apache.org/release-download-pages.html</a><br>
- <a href="https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features" \
rel="noreferrer" target="_blank">https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features</a><br>
- <a href="https://infra.apache.org/website-guidelines.html" rel="noreferrer" \
target="_blank">https://infra.apache.org/website-guidelines.html</a><br>
- <a href="https://infra.apache.org/project-site.html" rel="noreferrer" \
target="_blank">https://infra.apache.org/project-site.html</a><br> <br>
I like that Beam has the website in the main repo, but notably the<br>
INFRA recommendation is that we use a separate repo for the website<br>
(named `avro-site` though). Any thoughts? It's always something we<br>
can try and change later! Would it make it easier for the javadoc and<br>
other languages if they were in the same repo, or does it make little<br>
difference?<br></blockquote><div><br></div><div>Since some docs are generated by \
other tools (C/C++/C#) and they need to be copied to the rest of the website I agree \
that it would be easier if the website is in the main repo!</div><div>Also any \
changes to the spec/IDL will be in one PR (same repo) instead of two \
(main+website).</div><div> </div><blockquote class="gmail_quote" style="margin:0px \
0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> <br>
The old site actually contains all of the documentation for EVERY<br>
release, which can be found here:<br>
<br>
- <a href="https://svn.apache.org/repos/asf/avro/site/publish/docs/" rel="noreferrer" \
target="_blank">https://svn.apache.org/repos/asf/avro/site/publish/docs/</a><br>
- <a href="https://avro.apache.org/docs/" rel="noreferrer" \
target="_blank">https://avro.apache.org/docs/</a><br> <br>
Would it be tricky to adjust your work to mirror the existing<br>
structure for existing docs? I'm not even too fussy about not<br>
breaking the links in /docs/current/ but all of the existing pages<br>
such as /docs/1.7.7/ should be maintained if \
possible!<br></blockquote><div><br></div><div>I could make the \
"Documention" nav tab into a dropdown with menu items, one for each \
version.</div><div>1.11.0 and 1.10.2, and any future release, will be proper Markdown \
documents. The menu items for all previous versions will be links to the respective \
folder at <a href="https://avro.apache.org/docs/" \
target="_blank">https://avro.apache.org/docs/</a>.</div></div></div></blockquote><div><br></div><div>Done!</div><div><a \
href="https://avro-website.netlify.app/">https://avro-website.netlify.app/</a><br></div><div> \
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px \
solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div \
class="gmail_quote"><div>If someone wants to migrate some more old docs to Markdown \
then please fork the repo and send a PR!</div><div> </div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid \
rgb(204,204,204);padding-left:1ex"> <br>
There's so many good suggestions here for future work and improving<br>
our message and communication, I created<br>
<a href="https://issues.apache.org/jira/browse/AVRO-3264" rel="noreferrer" \
target="_blank">https://issues.apache.org/jira/browse/AVRO-3264</a> to point to \
this<br> discussion after we get this up.<br>
<br>
Thanks again for your great work!<br>
<br>
Ryan<br>
<br>
On Thu, Nov 4, 2021 at 4:26 PM Lee Hambley <<a href="mailto:lee.hambley@gmail.com" \
target="_blank">lee.hambley@gmail.com</a>> wrote:<br> ><br>
> I speak only for myself, but I am working in an environment where I am regularly \
checking docs all the way back to 1.8.x because we have legacy systems we cannot \
upgrade, and I am often referencing rules about schema canonical form. I value a lot \
the sidebar bottom version switching navigation from sites such as here <a \
href="https://fastavro.readthedocs.io/en/latest/writer.html#using-the-record-hint-to-specify-which-branch-of-a-union-to-take" \
rel="noreferrer" target="_blank">https://fastavro.readthedocs.io/en/latest/writer.html#using-the-record-hint-to-specify-which-branch-of-a-union-to-take</a> \
... but I know it can be extraordinarily difficult to make it work correctly with \
these static site generators.<br> ><br>
> Lee Hambley<br>
> <a href="http://lee.hambley.name/" rel="noreferrer" \
target="_blank">http://lee.hambley.name/</a><br> > +49 (0) 170 298 5667<br>
><br>
><br>
> On Thu, 4 Nov 2021 at 16:23, Martin Grigorov <<a \
href="mailto:mgrigorov@apache.org" target="_blank">mgrigorov@apache.org</a>> \
wrote:<br> >><br>
>><br>
>><br>
>> On Thu, Nov 4, 2021 at 5:04 PM Ismaël Mejía <<a \
href="mailto:iemejia@gmail.com" target="_blank">iemejia@gmail.com</a>> wrote:<br> \
>>><br> >>> Wow this is pretty neat ! Nice job Martin! A modern \
website can<br> >>> encourage more contributions.<br>
>>> I am more interested on content than aesthetics first. Is everything<br>
>>> already migrated? Anything missing? Any issue to report?<br>
>><br>
>><br>
>> Everything is migrated for the documentation of the *current* version.<br>
>> The old site contains documentation for both current and current-1. Is this \
something you would like to preserve ?<br> >><br>
>>><br>
>>><br>
>>><br>
>>> On Tue, Nov 2, 2021 at 7:01 PM Martin Grigorov <<a \
href="mailto:mgrigorov@apache.org" target="_blank">mgrigorov@apache.org</a>> \
wrote:<br> >>> ><br>
>>> > Hi,<br>
>>> ><br>
>>> > Anyone willing to send a PR with the suggested improvement?<br>
>>> > Or at least open an issue with the well formulated text and I will \
add it!<br> >>> ><br>
>>> > Regards,<br>
>>> > Martin<br>
>>> ><br>
>>> > On Tue, Nov 2, 2021, 18:08 Oscar Westra van Holthe - Kind <<a \
href="mailto:oscar@westravanholthe.nl" \
target="_blank">oscar@westravanholthe.nl</a>> wrote:<br> >>> >><br>
>>> >> Hi,<br>
>>> >><br>
>>> >> This is a huge improvement. Responsive, excellent navigation, \
syntax<br> >>> >> highlighting, ...<br>
>>> >><br>
>>> >> The only downside I see was already mentioned by Lee: the \
landing page is<br> >>> >> too empty (also in a mobile browser).<br>
>>> >> I think we could really benefit from mentioning the unique \
selling point of<br> >>> >> Avro here: "Your Data. Any Time, \
Anywhere." And then mention the language<br> >>> >> availability \
& excellent schema evolution.<br> >>> >><br>
>>> >> Kind regards,<br>
>>> >> Oscar<br>
>>> >><br>
>>> >> On Thu, 28 Oct 2021 at 10:43, Martin Grigorov <<a \
href="mailto:mgrigorov@apache.org" target="_blank">mgrigorov@apache.org</a>> \
wrote:<br> >>> >><br>
>>> >> > Hi all,<br>
>>> >> ><br>
>>> >> > Please check the new candidate for Apache Avro \
website:<br> >>> >> > <a href="https://avro-website.netlify.app/" \
rel="noreferrer" target="_blank">https://avro-website.netlify.app/</a><br> \
>>> >> ><br> >>> >> > It is based on Hugo and \
uses Docsy theme.<br> >>> >> > Its source code and instructions how \
to build could be found at<br> >>> >> > <a \
href="https://github.com/martin-g/avro-website" rel="noreferrer" \
target="_blank">https://github.com/martin-g/avro-website</a>.<br> >>> \
>> > The JIRA ticket is: <a \
href="https://issues.apache.org/jira/browse/AVRO-2175" rel="noreferrer" \
target="_blank">https://issues.apache.org/jira/browse/AVRO-2175</a><br> >>> \
>> ><br> >>> >> > I am not web designer, so some things \
may look not finished.<br> >>> >> > I've just copied the HTML \
content from the old site (<br> >>> >> > <a \
href="https://avro.apache.org/" rel="noreferrer" \
target="_blank">https://avro.apache.org/</a>) and converted it to Markdown for \
Hugo.<br> >>> >> ><br>
>>> >> > Any feedback is welcome! With Pull Requests would be \
awesome!<br> >>> >> ><br>
>>> >> > Regards,<br>
>>> >> > Martin<br>
>>> >> ><br>
</blockquote></div></div>
</blockquote></div></div>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic