mkdocs material

[knadh]

CC @rahulporuri

1. I'd recommend switching to the mkdocs-material theme, which is far more usable and legible. Eg: https://listmonk.app/docs - Ref: https://github.com/knadh/listmonk/blob/master/docs/docs/mkdocs.yml

2. If we're going to have multiple playbooks and handbooks, isn't it better to have one repository (and also one site) for all of it? eg: @fossunited/handbooks rather than one repo per handbook which is tedious?

[rahulporuri]

I'd recommend switching to the mkdocs-material theme, which is far more usable and legible. Eg: https://listmonk.app/docs - Ref: https://github.com/knadh/listmonk/blob/master/docs/docs/mkdocs.yml

Thanks for the recommendation. We wanted to experiment with the various themes and the material theme is first on our list.

If we're going to have multiple playbooks and handbooks, isn't it better to have one repository (and also one site) for all of it? eg: @fossunited/handbooks rather than one repo per handbook which is tedious?

One site - Definitely. It'd be great to have a single landing page that points to all of the handbooks. It will make it easier for us to link to the handbooks from the website, improving discoverability.

One GitHub repository - Maybe? I don't know? I wanted to play around with the different options e.g. mdbook in foss club handbook and mkdocs here and maybe sphinx + rst for indiafoss handbook (and maybe gitbook for the foundation handbook). Purely to experiment with the various options and also to make the community aware of the various options that exist. If we want to go this route, it might potentially be confusing to contributors if all of these live in the same repository. Especially confusing for beginners (e.g. students who are just trying to add a link or a few sentences regarding an awareness/action session).

The different repos also have differing audience/activity - foss hack and india foss handbooks will likely only be modified in short bursts during the events whereas the foss club handbook will likely be regularly updated (monthly, if not weekly). The FH and IF handbooks will also likely only be updated by volunteers whereas the club handbook will hopefully be taken over by the student club members, contributing material, references, notes regarding specific sessions, etc.

-> I came up with the above explocot rationale after you asked the question but it was instinctively/implicitly why I created separate repos.

[knadh]

hm, from a UX perspective, a handbooks.fossunited.org is the better choice. Like any other Wiki or a directory or an info repository. Ultimately, multiple handbooks are essentially a Wiki / knowledge repository. Multiple subdomains for each handbook is not good UX, and multiple repositories are also going to be an operational headache.

Experimenting with different tools/styles etc., sure, but that doesn't necessitate different repositories. That's a tactical / operational detail.

Different handbooks evolving differently in the same repository is also absolutely fine. For compartmentalising discussions about a FOSSHack handbook vs. IndiaFOSS handbook vs. a club handbook, tagging those issues will suffice, or categorizing them in GitHub discussions.

[rahulporuri]

Experimenting with different tools/styles etc., sure, but that doesn't necessitate different repositories. That's a tactical / operational detail.

It should be possible. I think. I'll have to experiment.

[ansharora28]

I like the idea of experimenting with different tools but isn't it better to maybe just decide on one theme and project we can use, which suits our needs and is also beginner friendly?

I don't think it's good UX if all the handbooks listed on handbooks.fossunited.org have different design themes etc. and require you to install different handbook tools. This might get even tedious for those who want to contribute to different handbooks.

I guess we should just experiment with all the different options internally and just decide on one? I'm almost done with the IndiaFOSS handbook made in mdbook and found it incredibly easy to work with, but i haven't put any thought into themes yet.

docs.fossunited.org also looks pretty good

[knadh]

+1

I'd recommend switching to the mkdocs-material theme, which is far more usable and legible. Eg: https://listmonk.app/docs - Ref: https://github.com/knadh/listmonk/blob/master/docs/docs/mkdocs.yml

docs.fossunited.org also looks pretty good

Yep. That site uses the mkdocs-materials theme.