Decide where content team documentation should be placed

benoit74 commented 8 months ago

Currently, it looks like there are a lot of places where documentation about content edition is placed, and I probably miss some locations.

This documentation is about:

what is the overall process of content edition (high level picture of how do we go from a zim request to a published ZIM)
how do we configure an offliner kind (youtube, mwoffliner, ...)

Some documentation is stored in various google docs (and I don't know where most of them are stored).

Some documentation is placed in the Zimfarm wiki (https://github.com/openzim/zimfarm/wiki), e.g. https://github.com/openzim/zimfarm/wiki/Ticket-Lifecycle-(Zimit), https://github.com/openzim/zimfarm/wiki/Tickets-Lifecycle-(Mwoffliner), https://github.com/openzim/zimfarm/wiki/Youtube-scraper-configuration-and-debug

And I just added a new location with Kiwix content Google shared drive.

I find this situation not convenient because:

the various google docs are not centralized and will probably get lost at some point ; from my experience, every team document created in Google drive must be placed in a Google Shared drive and this Shared drive must be shared with appropriate persons of the team
the documentation placed in Zimfarm wiki is mixed with very technical content for devs/ops
Github wikis do not allow at all a review process, every change is immediately implemented in production
Github wikis do not allow to have "folders" of documentation to structure stuff

From my perspective we should have:

a central, public, reviewable, dedicated location for most documentation
a very small Google shared drive (or something else) only for documentation which cannot be made public (like the API keys file I just created since these are secrets)

WDYT? Did I missed some locations? What would you suggest?

benoit74 commented 7 months ago

Is this task considered challenging, making it unclear how to respond? Alternatively, is it possible that there is a lack of interest because documentation is perceived as a less prioritized topic?

RavanJAltaie commented 7 months ago

Hi Benoit, I agree with your points above. We should have all documents placed in one place to be more accessible and organized. What about storing everything in the shared drive you created earlier? If agreed by @Popolechien , I'll start placing everything there.

benoit74 commented 7 months ago

The problem with this Google Drive is that it is not a public repository (while most Kiwix documentation must be public AFAIK). I think however that we could split the drive in two parts, a public one (with most content) and a private one (with Youtube API keys for instance).

Popolechien commented 7 months ago

Not a huge fan of Google Drive for public-facing documents - I would limit its use to API keys and other sensitive info as you suggest.

@benoit74 I am not sure I understand your reluctance to use the Github wiki. As I see it at /zimfarm/wiki there is a clear table of content listing the different documents needed to run/operate the farm

Github wikis do not allow at all a review process, every change is immediately implemented in production

This one sentence I did not understand. You mean there is no versioning (as opposite to a regular wiki)? Not ideal, but then if this is the only issue we could fall back to wiki.kiwix.org (not my preferred choice as I think staying close to the repo and limiting the number of platforms is key).

benoit74 commented 7 months ago

As discussed today during meeting, I only listed limitations I found in Github wiki, but I still agree it is a good choice, and yes I was speaking about versioning, and I strongly adhere to the advantages you listed.

We (@RavanJAltaie @Popolechien @benoit74) decided that:

we will host all scraper manuals in https://github.com/openzim/zimfarm/wiki
except private information (only Youtube API keys for now) which will be hosted in GDrive

Thank you all!

kelson42 commented 7 months ago

Sorry to come late but to me this is a no brainer as it is like for any software:

As far as possible software should be simple, before documenting, the software should be modified if necessary.
Then software should be basically auto-documented with a proper usage()
Things which are still unclear should be documented (a FAQ might be an appropriate form) at the place of the software, for us gothib wiki is a good candidate.
Then we have a set of goals/principles/policies/processes/howto/rules which are very specific to the content mgmt team. For this www.openzim.org is probably the right place because its an ombrella wiki. openzim/overview would be an alternative. openzim/zimfarm or openzin/cms wikis are kind of too specific.

Important is to tacle need of documentation at the right level and in the right order (no need to document something in content mgmt if basic software doc is not made - for example).

benoit74 commented 7 months ago

@kelson42 then I suggest we discuss it live, this looks like a difficult discussion where we do not agree at all. It is very sad that your comment come so late in the discussion, it is not like if it couldn't have been anticipated

Who would like to participate (again) to the live discussion?

Popolechien commented 7 months ago

Yeah count me in. Though if I understand right that gothib actually means github there might not be too much of a disagreement.

kelson42 commented 7 months ago

@kelson42 then I suggest we discuss it live, this looks like a difficult discussion where we do not agree at all. It is very sad that your comment come so late in the discussion, it is not like if it couldn't have been anticipated

Who would like to participate (again) to the live discussion?

I can emphasis that I have said this clearly during our content meeting (I think I have participated to only one) end of September. What I have written here is very straight, clear, and what has been practiced so far... not much to discuss IMO.

What I have also said many times is that the duty of the developers is to document clearly their software for the users. At this stage this is one of the most urgent thing the developers have to fix (in the context of content mgmt). This comes before trying to help the content team with there own organizational difficulties.

That said, I'm available next Friday if there is anything left to discuss.

openzim / overview

Decide where content team documentation should be placed #23