Re: Google Summer of Docs proposal 2021

[Andre Klapper <ak-47 gmx net>]

Hi,

thanks for the quick reply. Comments inline.

On Mon, 2021-03-15 at 09:35 -0700, Sriram Ramkrishna wrote:
> On Mon, Mar 15, 2021 at 9:08 AM Andre Klapper <ak-47 gmx net> wrote:
> > On Mon, 2021-03-15 at 08:11 -0700, Sriram Ramkrishna wrote:
> > > I'm working on a GSoD for this year and I've outlined the proposal.
> > I
> > > just wanted to give you all a heads up. I'm mostly focusing on our
> > wiki
> > > and looking to remove everything updated, and update the ones that
> > are
> > > still valid. But we will also use that experience to build a better
> > > onboarding experience by building a more supportable project
> > > documentation setup that can be managed for the future.
> > >
> > > If you have any thoughts, questions, or comments that would be
> > > appreciated. Here is the current proposal.
> > >
> > > https://etherpad.gnome.org/p/gsod-2021-proposal
> >
> > I'm trying to understand the scope and complexity of this.
> >
> > About how many pages are there to audit?
>
>
> I don't know off hand. The first phase is to audit it to find the scope
> and then flag things for removal or flag for update.


Does this imply that both applicants and mentors do not know if the
proposal is about spending time reviewing a hundred pages or if the
proposal is about spending a bit more time reviewing a million pages?


> > For the "work with community members", have those community members
> > committed to allocating sufficient resources?
>
>
> I haven't secured any resources. In that particular case, when I say
> work with community members, I mean - asking the owner of that project
> - "is this information current or can I delete it" So the commitment is
> to answer questions about the utility of the content. Primarily I see
> my role here to make the introductions on how to talk to - eg I am the
> guide/map for stuff in the wiki.


Assuming it takes a while to identify the "owner of that project"
related to each page, and then finding ways to contact them (e.g. email
addresses), and assuming that 80% will not reply (that's more or less
my impression from trying to contact maintainers about their projects'
tickets left in Bugzilla a few months ago), how does this influence the
success criteria for this project and the motivation of the applicant?


> > If it's about "building a better onboarding experience", is there an
> > analysis available what's bad about the current onboarding experience
> > with specific regard to the wiki?
>
>
> Only the one analysis I did about two years ago when I went through
> them. 
> There was enough wrong information that onboarding would have been
> confusing. I am not sure if I still have the etherpad where I had my
> notes there - but it was at our last combined hackfest with the docs
> team, engagement team and gtk team. That analysis/audit was only about
> 2 levels deep though.


Ah, great. Could you provide a link please?


> Part of what I want to do is also start focusing on keeping metrics -
> so a better onboarding experience also means measuring things better
> within the project.
>
> > If it's about "building a more supportable project documentation
> > setup", is there an analysis about the current pain points and how
> > this
> > plays along in combination with documentation in other places such
> > as
> > help.gnome.org, GitLab wiki pages, or GitLab README.md files?
>
>
> I'm not aware of any analysis - the idea of this project is to do
> exactly that. The idea is we build a proposal and that proposal has
> to include the current pain points (otherwise how does it become
> better?) and then we need to convince ourselves that this is a good
> solution going forward.
>
> I think the current wiki setup has not been particularly good if not
> altogether ignored. Part of that problem is our own set of process,
> but the bulk of our information is moving into gitlab and maybe
> gitlab is the right answer, but it needs to be investigated. I don't
> think this is an easy project to do - especially when it comes down
> to consensus. That's why the project is focused on a proposal as the
> end result - not to implement but at least debate.


Could you elaborate on "the current wiki setup has not been
particularly good"? Is this about taxonomy of content (subpage
structure etc), consistency of content (e.g. shared templates for app
page layout), or is this about some technical aspects?

Thanks,
andre
--
Andre Klapper  |  ak-47 gmx net
https://blogs.gnome.org/aklapper/