Re: Google Summer of Docs proposal 2021

[Sriram Ramkrishna <sri ramkrishna me>]

Hi Andre! Great questions. I'll try to answer.

On Mon, Mar 15, 2021 at 9:08 AM Andre Klapper <ak-47 gmx net> wrote:

Hi,

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 "remove" mean deleting pages (and making URLs become 404s if you
don't manually [[REDIRECT]]), or 'only' removing content from pages?

Remove means archive in this case. I don't want to delete anything permanently - they are historical and in the case of projects might be useful either to be possibly revived or for historical context.

There are some that just have wrong information altogether and hasn't been touched in many years. Those will either be updated or retired completely.

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.

"looking at alternative documentation technologies" means potentially
replacing the MoinMoin installation by moving stuff to Gitlab (or so)?

Yes. But that's part of an overall revamp of our web infrastructure. It's due for a major rehaul and so the two need to work together.

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.

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.

Cheers,

sri

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