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