Hi lewismc,
It's a good topic about the Tez doc. I totally agree with you that
current Tez doc could not attract more users&developers. A good doc will be the
first step to let new users to take part in. I think it's time to overhaul Tez
doc.
BTW, As a good partner of Tez, Hive has lots of internal
optimization&execution doc which relate to Tez, so I think if we want to do a
complete renovation about Tez doc, we also need to consider how to combine Hive
doc to do this.
I also send this thread to dev@hive. I hope some folks from hive
can also give more insightful thought.
Thanks,
Butao Zhang
---- Replied Message ----
| From | lewis john mcgibbney<lewi...@apache.org> |
| Date | 9/7/2024 03:15 |
| To | <d...@tez.apache.org> |
| Subject | Overhaul Tez Documentation |
Hi Tez dev@,
I recognize that this thread is running in parallel with a dev@ discussion
regarding concerns about and steps to prevent Tez from being moved to the
Attic… but I thought I’d send it none-the-less.
I wanted to start a thread regarding reorganizing/overhauling the
presentation of Tez website and wiki documentation.
<gripe>
One of the things which turned me away from Tez initially was the sparse
documentation. I found myself piecing together breadcrumbs of information
before I was able to do anything remotely useful. This is not particularly
welcoming to new/prospective users.
</gripe>
I think that something can be done about the above and I would like this
thread to focus on some proposed improvements which would
* lower the barrier to new prospective Tez users
* assist moderate to advanced Tez users in contributing more documentation.
* provide the Tez project with a long-overdue facelift and public-facing
image.
Some areas for consideration/ideas
* let’s gather suggestions for a content management framework which
facilitates a smooth authoring and publication workflow (for example I’ve
used https://jekyllrb.com/ with some success in the past).
* I would suggest that we deprecate the wiki (
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=30758956)
and migrate content to the new website likely under a technical
documentation navigation.
* I suggest that we archive all content relating to legacy Tez versions.
There’s quite a lot of content peppered throughout the wiki which
interrupts smooth reading.
* we need to produce a simple getting started guide which focuses on
intuitive examples and doesn’t burden the user with installation and
environments blockers before they can see what Tez does.
* we should archive all broken resources on the website e.g. users group
I hope the above will spur some conversation. I will also state that I am
willing to roll my sleeves up and make the above happen. Any input from dev@
is really appreciated. My goal would be to create a plan and then gradually
hack away at it.
Thanks
lewismc
