lead writer - you?

[Karsten Wade]

We could use someone to take full responsibility for the start to
publish for each of these guides, ongoing for now and possibly future
releases:

* Release Notes
* Installation Guide
* Packaging Guide
* User Guide

Interested?  Want to hear more?

There are a few more out there (Virtualization Guide, RPM Guide) that
could be picked up as well.

https://fedoraproject.org/wiki/Docs_Project_content_tasks_for_experienced_co...

- Karsten

[David Nalley]

On Thu, Oct 16, 2008 at 11:35 PM, Karsten 'quaid' Wade  wrote:
> We could use someone to take full responsibility for the start to
> publish for each of these guides, ongoing for now and possibly future
> releases:
> Release Notes
> Installation Guide
> Packaging Guide
> User Guide
>
> Interested?  Want to hear more?

So the pieces I see as missing from this posting are:

What are the responsibilities of a lead writer (hopefully a more
verbose explanation than 'everything')
What are the qualifications for a lead writer?
What is the typical time investment for a lead writer?
What tools are used and which of those need to be known ahead of time?

[Oisin Feeley]

On Fri, 17 Oct 2008 14:09:51 -0400, "David Nalley"
 said:
> On Thu, Oct 16, 2008 at 11:35 PM, Karsten 'quaid' Wade 
> wrote:
> > We could use someone to take full responsibility for the start to
> > publish for each of these guides, ongoing for now and possibly future
> > releases:
> > Release Notes
> > Installation Guide
> > Packaging Guide
> > User Guide
> >
> > Interested?  Want to hear more?
>
> So the pieces I see as missing from this posting are:
>
> What are the responsibilities of a lead writer (hopefully a more
> verbose explanation than 'everything')
> What are the qualifications for a lead writer?
> What is the typical time investment for a lead writer?
> What tools are used and which of those need to be known ahead of time?

I'd find this useful too. I am interested in all except the Packaging
Guide, but although I have some DocBook experience I'd like to have a
better idea of what the task is before I jump in.

Best wishes

[Paul W. Frields]

On Sun, 2008-10-19 at 20:44 -0400, Oisin Feeley wrote:
> On Fri, 17 Oct 2008 14:09:51 -0400, "David Nalley"
>  said:
> > On Thu, Oct 16, 2008 at 11:35 PM, Karsten 'quaid' Wade 
> > wrote:
> > > We could use someone to take full responsibility for the start to
> > > publish for each of these guides, ongoing for now and possibly future
> > > releases:
> > > Release Notes
> > > Installation Guide
> > > Packaging Guide
> > > User Guide
> > >
> > > Interested?  Want to hear more?
> >
> > So the pieces I see as missing from this posting are:
> >
> > What are the responsibilities of a lead writer (hopefully a more
> > verbose explanation than 'everything')
> > What are the qualifications for a lead writer?
> > What is the typical time investment for a lead writer?
> > What tools are used and which of those need to be known ahead of time?
>
> I'd find this useful too. I am interested in all except the Packaging
> Guide, but although I have some DocBook experience I'd like to have a
> better idea of what the task is before I jump in.

Since there are people popping up to take these responsibilities, it's
important to lay out answers to these questions.  That will help us keep
momentum going even during a lull in release notes progress, which I
realize has been on everyone's minds the past week or so.

[John J. McDonough]

----- Original Message ----- 
From: "Paul W. Frields" 
To: "For participants of the Documentation Project" 

Sent: Tuesday, October 21, 2008 1:17 PM
Subject: Re: lead writer - you?
> Since there are people popping up to take these responsibilities,
> it's important to lay out answers to these questions.

Time to run a class on IRC maybe?

--McD

[Karsten Wade]

On Tue, Oct 21, 2008 at 01:29:47PM -0400, John J. McDonough wrote:
> ----- Original Message ----- From: "Paul W. Frields" 
>
> To: "For participants of the Documentation Project"  
>
> Sent: Tuesday, October 21, 2008 1:17 PM
> Subject: Re: lead writer - you?
> > Since there are people popping up to take these responsibilities,
> > it's important to lay out answers to these questions.
>
> Time to run a class on IRC maybe?

Good idea, I'm down for a few of those.

Anyone want to help coordinate the schedules?

[Karsten Wade]

Wow, I never finished this, sorry ...

On Fri, 2008-10-17 at 14:09 -0400, David Nalley wrote:
> So the pieces I see as missing from this posting are:

Thanks, always good to prod me for more information.  Sometimes I don't
know that I know what I know and others don't know it. :)
> What are the responsibilities of a lead writer (hopefully a more
> verbose explanation than 'everything')

"Everything."

The idea of a lead writer is similar to a project manager.  It is
someone who is ultimately _accountable_ for making sure something is
brought to completion.  (Detailed list below.)  That is different from
being _responsible_ for each part.  Multiple people can share that
responsibility, but only one person can really be accountable.

IMO, this is a lot to ask of a person volunteering their time.  It's
similar to owning a software package, except I think it is generally
harder.  It is actually more akin to being the lead developer in an
upstream project *and* the downstream packager.

For that reason, I think the idea of a lead writer accountable for so
much is not sustainable.  It is a stop-gap answer until we can do more
with automating many of the functions a lead writer has to do manually
right now.  Automation (CMS) combined with defined processes and a
highly visible list of work to do for each release is going to turn the
lead writer job in to something much more like a software packager.

So:

''Current Lead Writer Accountable For:''

* Work with project leaders to set schedule for each release
* (Help) recruit additional writers
* Parse the work for the document into individual responsibilities other
writers can take on
* Ensure all of that work is done in time for the schedule
** May have to do the work yourself if no one takes on the job or is
unable to complete in time
* Deliver translation files according to the schedule
* Edit or coordinate editing
* Final polish, packaging (if done), and publication (on docs.fp.o)

''Ideal Lead Writer Accountable For:''

* As above, except:
** Once the schedule is set, it can be fixed in to the CMS
** Self-service for writers/editors to take on at-will
** Connect with project-wide recruitment
** Minimizes chances of things slipping between the cracks
** Translation files, packaging, and publication automated

Am I missing anything there?
> What are the qualifications for a lead writer?

* Be able and willing to be accountable for something from start to
finish
** Project management
* Do *not* need to be a highly accomplished writer or editor, but able
to recruit and direct people who can do those tasks
* Stick around or have been around long enough to fully understand the
job and be somewhat self-sufficient
* Enthusiasm and patience, especially patience
* Ability to nag without making enemies
> What is the typical time investment for a lead writer?

Hard to know other than personal experience.  For six of the months of a
year (non sequential months), the work load is small, maybe a few hours
a week of organization, writing, recruiting, and collaborating with
related sub-projects.

Presuming a reasonable amount of organization and tools that don't waste
time, during the more active of the six months, it should be:

* Five to ten hours a week for four+ months
* Ten to fifteen hours a week for the weeks leading up to freeze and release
> What tools are used and which of those need to be known ahead of time?

The full tool set can be learned on the job.  DocBook XML with either
the fedora-doc-utils or publican toolchain (or both?).  Wiki gardening
may be helpful.  Comfortable with using or learning multiple SCMs, in
specific, git, svn, and cvs are used currently.

One question you didn't ask was, Why do all this?  Maybe that is a
follow-up.  Presuming that one already wants to contribute to Fedora and
is balking at the potential time commitment, I focus on the fulfilling
aspects:

* Good for your career.  Red Hat has already hired from within the Docs
project, and other companies may do the same.  Your noted abilities as a
contributor to an important upstream means you are valuable for many
employers before they hire you.

* If you want to write and publish books, it's an impressive resume
builder.  In fact, because our work is openly licensed, you can use it
as the basis for a larger work.

* If you do your job well enough, you reduce the workload by splitting
it amongst many other people.  Take the release notes as an example.
That was a full-time person's job that we have turned in to a few hours
work each release for most of the contributors involved.

- Karsten

[Dale Bewley]

On Thu, 2008-10-16 at 20:35 -0700, Karsten 'quaid' Wade wrote:
> We could use someone to take full responsibility for the start to
> publish for each of these guides, ongoing for now and possibly future
> releases:
> Release Notes
> Installation Guide
> Packaging Guide
> User Guide
>
> Interested?  Want to hear more?
>
> There are a few more out there (Virtualization Guide, RPM Guide) that
> could be picked up as well.
>
> https://fedoraproject.org/wiki/Docs_Project_content_tasks_for_experienced_co...

I'm interested in working on the Virtualization Guide. Not knowing the
full implications of the "Guide" format or being a lead, and not yet
being very familiar with docbook, etc. I presume the best way to get
started is to just begin revising the virtualization quickstart guide[1]
with the idea it could become a "Guide" guide?

It's something I've pondered for quite a while. It looks to be in better
shape than I recalled. There was previously only a F8 specific guide.

Also, checking out the other guides[2] seems like a good idea. If Guide
has a formal definition, should there be a Guide category in MW? Is
there an index page I'm missing?

[1] https://fedoraproject.org/wiki/Virtualization_Quick_Start
[2] https://fedoraproject.org/wiki/User_Guide
https://fedoraproject.org/wiki/Administration_Guide
https://fedoraproject.org/wiki/Category:Draft_Documentation and of
course http://docs.fedoraproject.org/documentation-guide/

[Karsten Wade]

On Tue, Oct 21, 2008 at 08:14:26AM -0700, Dale Bewley wrote:
> I'm interested in working on the Virtualization Guide. Not knowing the
> full implications of the "Guide" format or being a lead, and not yet
> being very familiar with docbook, etc. I presume the best way to get
> started is to just begin revising the virtualization quickstart guide[1]
> with the idea it could become a "Guide" guide?

Yes, we can start with new page names and putting in the
[[Category:Draft Documentation]] tag.

https://fedoraproject.org/wiki/Help:Wiki_structure
> It's something I've pondered for quite a while. It looks to be in better
> shape than I recalled. There was previously only a F8 specific guide.
>
> Also, checking out the other guides[2] seems like a good idea. If Guide
> has a formal definition, should there be a Guide category in MW? Is
> there an index page I'm missing?

Hmm, that's not a bad idea.  Just as we might want [[Category:How
to]], why not [[Category:Guide]]?

One question is, do you intend to convert to XML or work only on the
wiki?  That dictates some of the details of how your organize it, etc.

Next you'll want to know the pos/neg for each choice. :)

- Karsten