Re: FreeBSD Documentation Portal status and review request

On Sun, Nov 21, 2021 at 07:03:48PM +0100, Fernando Apesteguía wrote:
> On Sun, Nov 21, 2021 at 5:31 PM Sergio Carlavilla
> <carlavilla@freebsd.org> wrote:
> >
> > Dear FreeBSD community,
> >
> > A couple of months ago we added information about the new FreeBSD
> > Documentation Portal to the quarterly reports[1].
> >
> > Well, at this time there's some things that need to be accomplished in the new
> > Documentation Portal. For example a local search using Algolia[2] as Hugo[3] or
> > AsciiDoctor[4] does. Algolia provides a free version for Open Source
> > projects[5].
> > And the dark theme.
> >
> > Apart from that, you can see the new Documentation Portal here[6]. I
> > used my personal
> > VPS to deploy the documentation portal temporarily to show to the
> > community since I have problems with Gitlab and Docker. I didn't add
> > all the languages because the bandwidth and the disk size is very
> > limited. I have the cheapest VPS in Digital Ocean hehe.
> >
> > To summarize the changes you are going to find:
> >
> > - Completely new responsive design. Tested in FreeBSD and all other major OS.
> > - Removed Python from the dependencies.
> > - Removed the list of figures, tables and examples.
> > Do you think these lists are useful? In this case I'll restore it
> > using the AsciiDoctor API instead of Python.
> >
> > This change will not be as traumatic as the previous one, it will not
> > be necessary
> > to freeze the repository or change the technology used to build the
> > documentation.
> > The existing theme will "just" be modified.
> >
> > Please let me know your thoughts about this :)
> > I'm gonna send this message to the documentation and translators list
> > to reach more people.
> 
> I like it very much. Thanks for working on this!


Thanks, Sergio, it is looking very nice. =)

> 
> A few details:
> 
> The "community" link seems broken. It points to
> https://carlavilla.es/en/communit
> 
> Font size at the fourth level of the titles seems a bit small to me.
> See the size difference between:
> 
> 3.2.2. Maintainer responsibilities
> 
> and
> 
> 3.2.2.1. Keep your ports up to date ---> This looks a bit small
> 
> in https://carlavilla.es/en/articles/contributing/
> 
> Can this be configured or do we rely on changing the font size in the browser?


We can let the trademark/copyright part be more formal and different
from the rest of the text.


> 
> My last question is about Algolia. I'm not familiar with it. Why do we
> plan to use it? What does it provide that Google or Duck Duck Go do
> not?

I'm not talking about Algolia or the other options [1] for the search
engine, but the idea here is to provide a custom search engine/page into
the documentation portal, like this [1].


The menu and table of content make it easy to navigate through the
documents' sections.

In the future, a search option in the page header will be excellent as
well.

The edit page button will be handy; we need to define the contributions
process through Github/Gitlab/etc.

Regards.

1 - https://gohugo.io/tools/search/
2 - https://ubuntu.com/server/docs
-- 
Danilo G. Baio (dbaio)