On Fri, 17 Oct 2008 14:09:51 -0400, "David Nalley" david.nalley@fedoraproject.org said:

On Thu, Oct 16, 2008 at 11:35 PM, Karsten 'quaid' Wade kwade@redhat.com 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

----- Original Message ----- From: "Paul W. Frields" stickster@gmail.com To: "For participants of the Documentation Project" fedora-docs-list@redhat.com 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

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

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