Re: 4.0 documentation - Confluence limitations?

[Ayush Saxena]

When we discussed last time, all of us were in favour and wanted to
have documentation as part of our website per version, but we realised
that isn't very much chasable considering the number of volunteers we
have, so we decided to go with improving the existing wiki pages & add
new additions to those existing pages. I went a step ahead and rather
than just tweaking those pages, created a separate space for 4.0
documentation, not sure if we would be able to complete that either
but that is a work in progress and a stop gap solution till we get the
documentation properly on our website. needless to say I am +1 on
coining a proper framework for the documentation & to get them on our
website.

-Ayush

On Mon, 8 Jan 2024 at 15:52, Simhadri G  wrote:
>
> Hi Zsolt,
>
> The current hive website is built with hugo,  so +1 from me :)
>
> We do have a few doc pages written in hugo, example :
> https://hive.apache.org/developement/quickstart/
>
> To add a new page we will need to add a new markdown file in the correct
> location in the hive-site repo and hugo will render the same in the hive
> website.
> For reference , there is a readme section here on how to add new pages as
> well: https://github.com/apache/hive-site#to-add-new-content
> We can definitely change the formatting/style of docs as needed.
>
>
> Thanks!
> Simhadri G
>
> On Mon, Jan 8, 2024 at 3:04 PM Stamatis Zampetakis 
> wrote:
>
> > Hey Zsolt,
> >
> > There have been a few discussions in the past about moving the
> > documentation from the wiki to the website and from what I recall
> > people were more or less in favor of moving towards this direction.
> > The main thing missing is volunteers that are willing to take on this
> > migration step.
> >
> > Personally, I am very much in favor of going into this direction not
> > only for solving namespacing issues but also for traceability purposes
> > and facilitating doc contributions and reviews.
> >
> > Big +1 from me.
> >
> > Best,
> > Stamatis
> >
> > On Mon, Jan 8, 2024 at 10:15 AM Zsolt Miskolczi
> >  wrote:
> > >
> > > In confluence, page names should be unique in a given space. As I see,
> > > Apache Hive has its own space.
> > > And now comes the tricky part: with 4.0 documentation, we didn't create a
> > > new space, just a 4.0 parent page. We create a copy of existing pages
> > under
> > > the umbrella of this page:
> > > https://cwiki.apache.org/confluence/display/Hive/Apache+Hive+4.0.0
> > >
> > > The problem is the unique naming of pages: it would make sense to keep
> > the
> > > page names the same as in the older documents but unfortunately, we
> > cannot.
> > > So we try to create names that are almost the same, or just delay the
> > > decisions.
> > > Two examples:
> > > - AdminManual Installation
> > > <
> > https://cwiki.apache.org/confluence/display/Hive/AdminManual+Installation>
> > > became Manual Installation
> > > 
> > > - Hive Schema Tool
> > > became
> > Copy
> > > of Hive Schema Tool - [TODO: move it under a 4.0 admin manual page, find
> > a
> > > proper name]
> > > <
> > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=284790216
> > >
> > >
> > > I feel multiple issues with that: Consistency is gone. And also, I'm not
> > > sure how it can support search engines. Also, it can be confusing for
> > > people who want to use the wiki pages.
> > >
> > > I was thinking about different solutions. Creating a Hive 4.0 space in
> > > Confluence can solve the problem of page uniqueness. But doesn't address
> > > the issue of searchability and ease of use.
> > >
> > > We can also keep the current one but in that case, it would be
> > recommended
> > > to figure out a great naming convention about the pages.
> > >
> > > At this point, my best idea is to move to an engine that has better
> > offers
> > > to document a software product. For example, Iceberg uses Hugo. It is a
> > > markup-based engine, it can be kept in source control and pretty fast.
> > > Example page: https://iceberg.apache.org/docs/1.4.1/.
> > >
> > >
> > > What do you think of that?
> > >
> > > Thank you,
> > > Zsolt
> >

Re: 4.0 documentation - Confluence limitations?

[Simhadri G]

Hi Zsolt,

The current hive website is built with hugo,  so +1 from me :)

We do have a few doc pages written in hugo, example :
https://hive.apache.org/developement/quickstart/

To add a new page we will need to add a new markdown file in the correct
location in the hive-site repo and hugo will render the same in the hive
website.
For reference , there is a readme section here on how to add new pages as
well: https://github.com/apache/hive-site#to-add-new-content
We can definitely change the formatting/style of docs as needed.


Thanks!
Simhadri G

On Mon, Jan 8, 2024 at 3:04 PM Stamatis Zampetakis 
wrote:

> Hey Zsolt,
>
> There have been a few discussions in the past about moving the
> documentation from the wiki to the website and from what I recall
> people were more or less in favor of moving towards this direction.
> The main thing missing is volunteers that are willing to take on this
> migration step.
>
> Personally, I am very much in favor of going into this direction not
> only for solving namespacing issues but also for traceability purposes
> and facilitating doc contributions and reviews.
>
> Big +1 from me.
>
> Best,
> Stamatis
>
> On Mon, Jan 8, 2024 at 10:15 AM Zsolt Miskolczi
>  wrote:
> >
> > In confluence, page names should be unique in a given space. As I see,
> > Apache Hive has its own space.
> > And now comes the tricky part: with 4.0 documentation, we didn't create a
> > new space, just a 4.0 parent page. We create a copy of existing pages
> under
> > the umbrella of this page:
> > https://cwiki.apache.org/confluence/display/Hive/Apache+Hive+4.0.0
> >
> > The problem is the unique naming of pages: it would make sense to keep
> the
> > page names the same as in the older documents but unfortunately, we
> cannot.
> > So we try to create names that are almost the same, or just delay the
> > decisions.
> > Two examples:
> > - AdminManual Installation
> > <
> https://cwiki.apache.org/confluence/display/Hive/AdminManual+Installation>
> > became Manual Installation
> > 
> > - Hive Schema Tool
> > became
> Copy
> > of Hive Schema Tool - [TODO: move it under a 4.0 admin manual page, find
> a
> > proper name]
> > <
> https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=284790216
> >
> >
> > I feel multiple issues with that: Consistency is gone. And also, I'm not
> > sure how it can support search engines. Also, it can be confusing for
> > people who want to use the wiki pages.
> >
> > I was thinking about different solutions. Creating a Hive 4.0 space in
> > Confluence can solve the problem of page uniqueness. But doesn't address
> > the issue of searchability and ease of use.
> >
> > We can also keep the current one but in that case, it would be
> recommended
> > to figure out a great naming convention about the pages.
> >
> > At this point, my best idea is to move to an engine that has better
> offers
> > to document a software product. For example, Iceberg uses Hugo. It is a
> > markup-based engine, it can be kept in source control and pretty fast.
> > Example page: https://iceberg.apache.org/docs/1.4.1/.
> >
> >
> > What do you think of that?
> >
> > Thank you,
> > Zsolt
>

Re: 4.0 documentation - Confluence limitations?

[Stamatis Zampetakis]

Hey Zsolt,

There have been a few discussions in the past about moving the
documentation from the wiki to the website and from what I recall
people were more or less in favor of moving towards this direction.
The main thing missing is volunteers that are willing to take on this
migration step.

Personally, I am very much in favor of going into this direction not
only for solving namespacing issues but also for traceability purposes
and facilitating doc contributions and reviews.

Big +1 from me.

Best,
Stamatis

On Mon, Jan 8, 2024 at 10:15 AM Zsolt Miskolczi
 wrote:
>
> In confluence, page names should be unique in a given space. As I see,
> Apache Hive has its own space.
> And now comes the tricky part: with 4.0 documentation, we didn't create a
> new space, just a 4.0 parent page. We create a copy of existing pages under
> the umbrella of this page:
> https://cwiki.apache.org/confluence/display/Hive/Apache+Hive+4.0.0
>
> The problem is the unique naming of pages: it would make sense to keep the
> page names the same as in the older documents but unfortunately, we cannot.
> So we try to create names that are almost the same, or just delay the
> decisions.
> Two examples:
> - AdminManual Installation
> 
> became Manual Installation
> 
> - Hive Schema Tool
> became Copy
> of Hive Schema Tool - [TODO: move it under a 4.0 admin manual page, find a
> proper name]
> 
>
> I feel multiple issues with that: Consistency is gone. And also, I'm not
> sure how it can support search engines. Also, it can be confusing for
> people who want to use the wiki pages.
>
> I was thinking about different solutions. Creating a Hive 4.0 space in
> Confluence can solve the problem of page uniqueness. But doesn't address
> the issue of searchability and ease of use.
>
> We can also keep the current one but in that case, it would be recommended
> to figure out a great naming convention about the pages.
>
> At this point, my best idea is to move to an engine that has better offers
> to document a software product. For example, Iceberg uses Hugo. It is a
> markup-based engine, it can be kept in source control and pretty fast.
> Example page: https://iceberg.apache.org/docs/1.4.1/.
>
>
> What do you think of that?
>
> Thank you,
> Zsolt

4.0 documentation - Confluence limitations?

[Zsolt Miskolczi]

In confluence, page names should be unique in a given space. As I see,
Apache Hive has its own space.
And now comes the tricky part: with 4.0 documentation, we didn't create a
new space, just a 4.0 parent page. We create a copy of existing pages under
the umbrella of this page:
https://cwiki.apache.org/confluence/display/Hive/Apache+Hive+4.0.0

The problem is the unique naming of pages: it would make sense to keep the
page names the same as in the older documents but unfortunately, we cannot.
So we try to create names that are almost the same, or just delay the
decisions.
Two examples:
- AdminManual Installation

became Manual Installation

- Hive Schema Tool
became Copy
of Hive Schema Tool - [TODO: move it under a 4.0 admin manual page, find a
proper name]


I feel multiple issues with that: Consistency is gone. And also, I'm not
sure how it can support search engines. Also, it can be confusing for
people who want to use the wiki pages.

I was thinking about different solutions. Creating a Hive 4.0 space in
Confluence can solve the problem of page uniqueness. But doesn't address
the issue of searchability and ease of use.

We can also keep the current one but in that case, it would be recommended
to figure out a great naming convention about the pages.

At this point, my best idea is to move to an engine that has better offers
to document a software product. For example, Iceberg uses Hugo. It is a
markup-based engine, it can be kept in source control and pretty fast.
Example page: https://iceberg.apache.org/docs/1.4.1/.


What do you think of that?

Thank you,
Zsolt