QEMU participation to Google Season of Docs

QEMU participation to Google Season of Docs

[Philippe Mathieu-Daudé]

Hi,

Google recently announced their 'Season of Docs' project:
https://developers.google.com/season-of-docs

QEMU project seems to fit all the requirements.

Who is interested in [co-]mentoring?

Relevant links:
https://developers.google.com/season-of-docs/docs/admin-guide
https://developers.google.com/season-of-docs/docs/timeline

[Following is extracted from the previous links:]

Example projects:

* Build a documentation site on a platform to be decided
   by the technical writer and open source mentor, and publish
   an initial set of basic documents on the site. Examples of
   platforms include:

   - A static site generator such as Hugo, Jekyll, Sphinx, ...

* Refactor the open source project's existing documentation to
   provide an improved user experience or a more accessible
   information architecture.

* Write a conceptual overview of, or introduction to, a product
   or feature. Often a team creates their technical documentation
   from the bottom up, with the result that there's a lot of
   detail but it's hard to understand the product as a whole. A
   technical writer can fix this.

* Create a tutorial for a high-profile use case.

* Create a set of focused how-to guides for specific tasks.

* Create a contributor’s guide that includes basic information
   about getting started as a contributor to the open source
   project, as well as any rules around licence agreements,
   processes for pull requests and reviews, building the project,
   and so on.

Previous experience with similar programs, such as Google Summer
of Code or others: If you or any of your mentors have taken part
in Google Summer of Code or a similar program, mention this in
your application. Describe your achievements in that program.
Explain how this experience may influence the way you work in
Season of Docs.

The 2020 season of Season of Docs is limited to a maximum of
50 technical writing projects in total.
As a guideline, we expect to accept a maximum of 2 projects
per organization, so that we don't end up with too many
accepted projects. However, if the free selection process
doesn't fill all the slots, the Google program administrators
may allocate additional slots to some organizations.

Re: QEMU participation to Google Season of Docs

[Paolo Bonzini]

On 01/04/20 18:37, Philippe Mathieu-Daudé wrote:
> 
> * Refactor the open source project's existing documentation to
>   provide an improved user experience or a more accessible
>   information architecture.

This kind of project would be indeed very suitable to QEMU.  Stefan,
perhaps you could help by providing the text for our Summer of Code
submission?

Thanks,

Paolo

Re: QEMU participation to Google Season of Docs

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 747 bytes --]

On Wed, Apr 01, 2020 at 06:46:02PM +0200, Paolo Bonzini wrote:
> On 01/04/20 18:37, Philippe Mathieu-Daudé wrote:
> > 
> > * Refactor the open source project's existing documentation to
> >   provide an improved user experience or a more accessible
> >   information architecture.
> 
> This kind of project would be indeed very suitable to QEMU.  Stefan,
> perhaps you could help by providing the text for our Summer of Code
> submission?

Philippe, would you like to be the Google Season of Docs administrator
for QEMU?  I don't have enough bandwidth to be involved myself.

I can provide you the QEMU's GSoC 2020 application form which might have
useful snippets you can reuse for building a GSoD application for QEMU.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: QEMU participation to Google Season of Docs

[John Snow]

On 4/1/20 12:37 PM, Philippe Mathieu-Daudé wrote:
> Hi,
> 
> Google recently announced their 'Season of Docs' project:
> https://developers.google.com/season-of-docs
> 
> QEMU project seems to fit all the requirements.
> 
> Who is interested in [co-]mentoring?
> 
> Relevant links:
> https://developers.google.com/season-of-docs/docs/admin-guide
> https://developers.google.com/season-of-docs/docs/timeline
> 
> [Following is extracted from the previous links:]
> 
> Example projects:
> 
> * Build a documentation site on a platform to be decided
>   by the technical writer and open source mentor, and publish
>   an initial set of basic documents on the site. Examples of
>   platforms include:
> 
>   - A static site generator such as Hugo, Jekyll, Sphinx, ...
> 
> * Refactor the open source project's existing documentation to
>   provide an improved user experience or a more accessible
>   information architecture.
> 
> * Write a conceptual overview of, or introduction to, a product
>   or feature. Often a team creates their technical documentation
>   from the bottom up, with the result that there's a lot of
>   detail but it's hard to understand the product as a whole. A
>   technical writer can fix this.
> 
> * Create a tutorial for a high-profile use case.
> 
> * Create a set of focused how-to guides for specific tasks.
> 
> * Create a contributor’s guide that includes basic information
>   about getting started as a contributor to the open source
>   project, as well as any rules around licence agreements,
>   processes for pull requests and reviews, building the project,
>   and so on.
> 
> Previous experience with similar programs, such as Google Summer
> of Code or others: If you or any of your mentors have taken part
> in Google Summer of Code or a similar program, mention this in
> your application. Describe your achievements in that program.
> Explain how this experience may influence the way you work in
> Season of Docs.
> 
> The 2020 season of Season of Docs is limited to a maximum of
> 50 technical writing projects in total.
> As a guideline, we expect to accept a maximum of 2 projects
> per organization, so that we don't end up with too many
> accepted projects. However, if the free selection process
> doesn't fill all the slots, the Google program administrators
> may allocate additional slots to some organizations.
> 

This looks like it could be very good for us.

My only concern is that the scope and breadth of QEMU is huge and it may
be a lot for a newcomer to tackle appropriately for top-level docs, so I
feel like it requires a mentor who has a good understanding of the broad
picture of QEMU.

Like the description says, we often write things bottom-up in areas of
very specific focus. The broad picture is sometimes harder to conjure
accurately.

I have a lot of opinions and thoughts on python and how docs should be
laid out, but I'm afraid I'm not so good at understanding all of the
options and "use cases" of QEMU to confidently lay out a top-level TOC.
Maybe if we collaborated on a TOC we could give a clear project
guideline to a GSoC/GSoD contributor.

(Or maybe I'm overthinking it.)

--js

Re: QEMU participation to Google Season of Docs

[Ruben]

[-- Attachment #1: Type: text/plain, Size: 3542 bytes --]

Its ingoogle... We don't do google.



On April 3, 2020 9:37:09 PM EDT, John Snow <jsnow@redhat.com> wrote:
>
>
>On 4/1/20 12:37 PM, Philippe Mathieu-Daudé wrote:
>> Hi,
>> 
>> Google recently announced their 'Season of Docs' project:
>> https://developers.google.com/season-of-docs
>> 
>> QEMU project seems to fit all the requirements.
>> 
>> Who is interested in [co-]mentoring?
>> 
>> Relevant links:
>> https://developers.google.com/season-of-docs/docs/admin-guide
>> https://developers.google.com/season-of-docs/docs/timeline
>> 
>> [Following is extracted from the previous links:]
>> 
>> Example projects:
>> 
>> * Build a documentation site on a platform to be decided
>>   by the technical writer and open source mentor, and publish
>>   an initial set of basic documents on the site. Examples of
>>   platforms include:
>> 
>>   - A static site generator such as Hugo, Jekyll, Sphinx, ...
>> 
>> * Refactor the open source project's existing documentation to
>>   provide an improved user experience or a more accessible
>>   information architecture.
>> 
>> * Write a conceptual overview of, or introduction to, a product
>>   or feature. Often a team creates their technical documentation
>>   from the bottom up, with the result that there's a lot of
>>   detail but it's hard to understand the product as a whole. A
>>   technical writer can fix this.
>> 
>> * Create a tutorial for a high-profile use case.
>> 
>> * Create a set of focused how-to guides for specific tasks.
>> 
>> * Create a contributor’s guide that includes basic information
>>   about getting started as a contributor to the open source
>>   project, as well as any rules around licence agreements,
>>   processes for pull requests and reviews, building the project,
>>   and so on.
>> 
>> Previous experience with similar programs, such as Google Summer
>> of Code or others: If you or any of your mentors have taken part
>> in Google Summer of Code or a similar program, mention this in
>> your application. Describe your achievements in that program.
>> Explain how this experience may influence the way you work in
>> Season of Docs.
>> 
>> The 2020 season of Season of Docs is limited to a maximum of
>> 50 technical writing projects in total.
>> As a guideline, we expect to accept a maximum of 2 projects
>> per organization, so that we don't end up with too many
>> accepted projects. However, if the free selection process
>> doesn't fill all the slots, the Google program administrators
>> may allocate additional slots to some organizations.
>> 
>
>This looks like it could be very good for us.
>
>My only concern is that the scope and breadth of QEMU is huge and it
>may
>be a lot for a newcomer to tackle appropriately for top-level docs, so
>I
>feel like it requires a mentor who has a good understanding of the
>broad
>picture of QEMU.
>
>Like the description says, we often write things bottom-up in areas of
>very specific focus. The broad picture is sometimes harder to conjure
>accurately.
>
>I have a lot of opinions and thoughts on python and how docs should be
>laid out, but I'm afraid I'm not so good at understanding all of the
>options and "use cases" of QEMU to confidently lay out a top-level TOC.
>Maybe if we collaborated on a TOC we could give a clear project
>guideline to a GSoC/GSoD contributor.
>
>(Or maybe I'm overthinking it.)
>
>--js

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

[-- Attachment #2: Type: text/html, Size: 4156 bytes --]

Re: QEMU participation to Google Season of Docs

[Paolo Bonzini]

On 04/04/20 03:37, John Snow wrote:
> This looks like it could be very good for us.
> 
> My only concern is that the scope and breadth of QEMU is huge and it may
> be a lot for a newcomer to tackle appropriately for top-level docs, so I
> feel like it requires a mentor who has a good understanding of the broad
> picture of QEMU.
> 
> Like the description says, we often write things bottom-up in areas of
> very specific focus. The broad picture is sometimes harder to conjure
> accurately.
> 
> I have a lot of opinions and thoughts on python and how docs should be
> laid out, but I'm afraid I'm not so good at understanding all of the
> options and "use cases" of QEMU to confidently lay out a top-level TOC.
> Maybe if we collaborated on a TOC we could give a clear project
> guideline to a GSoC/GSoD contributor.

That's actually how a good technical writer can help us!  The main
problem we have with our docs is the disconnect between docs/system
(formerly qemu-doc) and the .txt files in docs/.  We know the material,
but it's hard to reorganize docs/system to make room for everything else.

Reorganizing the TOC to fit all the material in both categories would be
the best outcome of our participation in GSoD.

Paolo

Re: QEMU participation to Google Season of Docs

[Peter Maydell]

On Mon, 6 Apr 2020 at 11:35, Paolo Bonzini <pbonzini@redhat.com> wrote:
> On 04/04/20 03:37, John Snow wrote:
> > I have a lot of opinions and thoughts on python and how docs should be
> > laid out, but I'm afraid I'm not so good at understanding all of the
> > options and "use cases" of QEMU to confidently lay out a top-level TOC.
> > Maybe if we collaborated on a TOC we could give a clear project
> > guideline to a GSoC/GSoD contributor.
>
> That's actually how a good technical writer can help us!  The main
> problem we have with our docs is the disconnect between docs/system
> (formerly qemu-doc) and the .txt files in docs/.  We know the material,
> but it's hard to reorganize docs/system to make room for everything else.
>
> Reorganizing the TOC to fit all the material in both categories would be
> the best outcome of our participation in GSoD.

Yep, and unlike last year we've actually (almost) completed
the transition to Sphinx so we have a workable structure/tooling
for a tech writer to work with.

thanks
-- PMM

Re: QEMU participation to Google Season of Docs

[Philippe Mathieu-Daudé]

On 4/2/20 11:06 AM, Stefan Hajnoczi wrote:
> On Wed, Apr 01, 2020 at 06:46:02PM +0200, Paolo Bonzini wrote:
>> On 01/04/20 18:37, Philippe Mathieu-Daudé wrote:
>>>
>>> * Refactor the open source project's existing documentation to
>>>    provide an improved user experience or a more accessible
>>>    information architecture.
>>
>> This kind of project would be indeed very suitable to QEMU.  Stefan,
>> perhaps you could help by providing the text for our Summer of Code
>> submission?
> 
> Philippe, would you like to be the Google Season of Docs administrator
> for QEMU?  I don't have enough bandwidth to be involved myself.

Thankfully my manager approved this, so I'm in :)

> I can provide you the QEMU's GSoC 2020 application form which might have
> useful snippets you can reuse for building a GSoD application for QEMU.

That might help. I'll start the application draft.

Thanks,

Phil.

Re: QEMU participation to Google Season of Docs

[Ruben Safir]

never use google docs


On Mon, Apr 06, 2020 at 11:57:11AM +0100, Peter Maydell wrote:
> On Mon, 6 Apr 2020 at 11:35, Paolo Bonzini <pbonzini@redhat.com> wrote:
> > On 04/04/20 03:37, John Snow wrote:
> > > I have a lot of opinions and thoughts on python and how docs should be
> > > laid out, but I'm afraid I'm not so good at understanding all of the
> > > options and "use cases" of QEMU to confidently lay out a top-level TOC.
> > > Maybe if we collaborated on a TOC we could give a clear project
> > > guideline to a GSoC/GSoD contributor.
> >
> > That's actually how a good technical writer can help us!  The main
> > problem we have with our docs is the disconnect between docs/system
> > (formerly qemu-doc) and the .txt files in docs/.  We know the material,
> > but it's hard to reorganize docs/system to make room for everything else.
> >
> > Reorganizing the TOC to fit all the material in both categories would be
> > the best outcome of our participation in GSoD.
> 
> Yep, and unlike last year we've actually (almost) completed
> the transition to Sphinx so we have a workable structure/tooling
> for a tech writer to work with.
> 
> thanks
> -- PMM

-- 
So many immigrant groups have swept through our town
that Brooklyn, like Atlantis, reaches mythological
proportions in the mind of the world - RI Safir 1998
http://www.mrbrklyn.com 

DRM is THEFT - We are the STAKEHOLDERS - RI Safir 2002
http://www.nylxs.com - Leadership Development in Free Software
http://www2.mrbrklyn.com/resources - Unpublished Archive 
http://www.coinhangout.com - coins!
http://www.brooklyn-living.com 

Being so tracked is for FARM ANIMALS and extermination camps, 
but incompatible with living as a free human being. -RI Safir 2013