You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@training.apache.org by Rich Bowen <rb...@rcbowen.com> on 2024/09/20 18:22:34 UTC
Proposed reorg of "user" docs
As I’ve been working on the user docs, I see two (overlapping) audiences - presentation authors, and presenters. While they are often the same person, they are two separate skill sets, and I would like to divide the docs accordingly. Looking for objections before I proceed down this road. Thanks.
—Rich
—
Rich Bowen
rbowen@rcbowen.com
Re: Proposed reorg of "user" docs
Posted by Rich Bowen <rb...@rcbowen.com>.
> On Sep 20, 2024, at 2:38 PM, Andrew Wetmore <co...@gmail.com> wrote:
>
> This seems like a good idea, but I have a related question: are
> Powerpoint-style presentations the only mode of training materials that
> training.a.o intends to support? No templates for quizzes, tutorials,
> how-tos?
I asked this same question a couple of years ago, and the answer at the time (if I remember correctly) was “we want to do one thing well before we start to do other things poorly” or words to that effect, which seems like a good answer, in terms of not committing to too much up front. I would, however, really love to see the project expand into those spaces, eventually. Maybe. I don’t know. ‘Cause tutorials and howtos might better belong in the docs of the individual projects. This is worth further discussion. Being a central repository for docs for all projects would be chaos, so it is important to draw the line somewhere.
—
Rich Bowen
rbowen@rcbowen.com
Re: Proposed reorg of "user" docs
Posted by Andrew Wetmore <co...@gmail.com>.
This seems like a good idea, but I have a related question: are
Powerpoint-style presentations the only mode of training materials that
training.a.o intends to support? No templates for quizzes, tutorials,
how-tos?
a
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.www.avast.com
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
On Fri, Sep 20, 2024 at 3:23 PM Rich Bowen <rb...@rcbowen.com> wrote:
> As I’ve been working on the user docs, I see two (overlapping) audiences -
> presentation authors, and presenters. While they are often the same person,
> they are two separate skill sets, and I would like to divide the docs
> accordingly. Looking for objections before I proceed down this road. Thanks.
>
> —Rich
>
>
>
> —
> Rich Bowen
> rbowen@rcbowen.com
>
>
>
>
>
--
Andrew Wetmore
Editor, Moose House Publications <https://moosehousepress.com/>
Editor-Writer, The Apache Software Foundation <https://apache.org/>
Re: Proposed reorg of "user" docs
Posted by Christofer Dutz <ch...@c-ware.de>.
Sound good to me.
Chris
Gesendet von Outlook für Android<https://aka.ms/AAb9ysg>
________________________________
From: Rich Bowen <rb...@rcbowen.com>
Sent: Friday, September 20, 2024 8:49:14 PM
To: dev@training.apache.org <de...@training.apache.org>
Subject: Re: Proposed reorg of "user" docs
> On Sep 20, 2024, at 2:22 PM, Rich Bowen <rb...@rcbowen.com> wrote:
>
> As I’ve been working on the user docs, I see two (overlapping) audiences - presentation authors, and presenters. While they are often the same person, they are two separate skill sets, and I would like to divide the docs accordingly. Looking for objections before I proceed down this road. Thanks.
Specifically, here’s what I have in mind for structure:
User:
Presenting
Locally
building
Updating and rebuilding before each presentation
Where are the slides and how to open them
From t.a.o website (ie, using presentations directly from website)
Presentation tips (lots of screen shots, and pointing out nifty features)
Writing presentations
Creating new presentation
Authoring tips
Building/testing presentation
Submitting a new presentation to Training project
Pitching to the mailing list before opening a PR (What content is likely to be accepted)
How to open the PR (bare-bones GitHub instructions)
Patching existing presentations
Other stuff
Giving feedback/improvements on available presentations
Requesting new content (A template email for approaching projects with this request)
—
Rich Bowen
rbowen@rcbowen.com
Re: Proposed reorg of "user" docs
Posted by Rich Bowen <rb...@rcbowen.com>.
> On Sep 21, 2024, at 3:06 PM, Andrew Wetmore <co...@gmail.com> wrote:
>
> Will the 'Presentation tips' item include hints about how to, you know,
> present the thing (practice beforehand, write out essential phrases, eye
> contact, don't shift from foot to foot, dealing with dry mouth...)?
It certainly *could*, but I’m not sure to what degree that belongs in the official documentation. I welcome opinions on this.
—
Rich Bowen
rbowen@rcbowen.com
Re: Proposed reorg of "user" docs
Posted by Andrew Wetmore <co...@gmail.com>.
Will the 'Presentation tips' item include hints about how to, you know,
present the thing (practice beforehand, write out essential phrases, eye
contact, don't shift from foot to foot, dealing with dry mouth...)?
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.www.avast.com
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
On Sat, Sep 21, 2024 at 11:05 AM Craig Russell <ap...@gmail.com> wrote:
> Looks good!
>
> Craig
>
>
> > On Sep 20, 2024, at 11:49, Rich Bowen <rb...@rcbowen.com> wrote:
> >
> >
> >
> >> On Sep 20, 2024, at 2:22 PM, Rich Bowen <rb...@rcbowen.com> wrote:
> >>
> >> As I’ve been working on the user docs, I see two (overlapping)
> audiences - presentation authors, and presenters. While they are often the
> same person, they are two separate skill sets, and I would like to divide
> the docs accordingly. Looking for objections before I proceed down this
> road. Thanks.
> >
> > Specifically, here’s what I have in mind for structure:
> >
> >
> > User:
> >
> > Presenting
> > Locally
> > building
> > Updating and rebuilding before each presentation
> > Where are the slides and how to open them
> > From t.a.o website (ie, using presentations directly from
> website)
> > Presentation tips (lots of screen shots, and pointing out
> nifty features)
> > Writing presentations
> > Creating new presentation
> > Authoring tips
> > Building/testing presentation
> > Submitting a new presentation to Training project
> > Pitching to the mailing list before opening a PR
> (What content is likely to be accepted)
> > How to open the PR (bare-bones GitHub instructions)
> > Patching existing presentations
> > Other stuff
> > Giving feedback/improvements on available presentations
> > Requesting new content (A template email for approaching
> projects with this request)
> >
> > —
> > Rich Bowen
> > rbowen@rcbowen.com
> >
> >
> >
> >
>
> Craig L Russell
> clr@apache.org
>
>
--
Andrew Wetmore
Editor, Moose House Publications <https://moosehousepress.com/>
Editor-Writer, The Apache Software Foundation <https://apache.org/>
Re: Proposed reorg of "user" docs
Posted by Craig Russell <ap...@gmail.com>.
Looks good!
Craig
> On Sep 20, 2024, at 11:49, Rich Bowen <rb...@rcbowen.com> wrote:
>
>
>
>> On Sep 20, 2024, at 2:22 PM, Rich Bowen <rb...@rcbowen.com> wrote:
>>
>> As I’ve been working on the user docs, I see two (overlapping) audiences - presentation authors, and presenters. While they are often the same person, they are two separate skill sets, and I would like to divide the docs accordingly. Looking for objections before I proceed down this road. Thanks.
>
> Specifically, here’s what I have in mind for structure:
>
>
> User:
>
> Presenting
> Locally
> building
> Updating and rebuilding before each presentation
> Where are the slides and how to open them
> From t.a.o website (ie, using presentations directly from website)
> Presentation tips (lots of screen shots, and pointing out nifty features)
> Writing presentations
> Creating new presentation
> Authoring tips
> Building/testing presentation
> Submitting a new presentation to Training project
> Pitching to the mailing list before opening a PR (What content is likely to be accepted)
> How to open the PR (bare-bones GitHub instructions)
> Patching existing presentations
> Other stuff
> Giving feedback/improvements on available presentations
> Requesting new content (A template email for approaching projects with this request)
>
> —
> Rich Bowen
> rbowen@rcbowen.com
>
>
>
>
Craig L Russell
clr@apache.org
Re: Proposed reorg of "user" docs
Posted by Rich Bowen <rb...@rcbowen.com>.
> On Sep 20, 2024, at 2:22 PM, Rich Bowen <rb...@rcbowen.com> wrote:
>
> As I’ve been working on the user docs, I see two (overlapping) audiences - presentation authors, and presenters. While they are often the same person, they are two separate skill sets, and I would like to divide the docs accordingly. Looking for objections before I proceed down this road. Thanks.
Specifically, here’s what I have in mind for structure:
User:
Presenting
Locally
building
Updating and rebuilding before each presentation
Where are the slides and how to open them
From t.a.o website (ie, using presentations directly from website)
Presentation tips (lots of screen shots, and pointing out nifty features)
Writing presentations
Creating new presentation
Authoring tips
Building/testing presentation
Submitting a new presentation to Training project
Pitching to the mailing list before opening a PR (What content is likely to be accepted)
How to open the PR (bare-bones GitHub instructions)
Patching existing presentations
Other stuff
Giving feedback/improvements on available presentations
Requesting new content (A template email for approaching projects with this request)
—
Rich Bowen
rbowen@rcbowen.com