Proper graphic chart, better docs/website and some marketing

[jooola]

I don't really like the word marketing , but it kinda fits.

This ticket will address 3 related topics, our graphic chart, the docs/website and some marketing.

Graphic charter

Libretime currently doesn't have a real graphic chart and/or most of it is based on Airtime.

Comparing the 2 websites:

Logo is almost the same, colors are similar, homepage structure ...

I propose to define a proper brand for Libretime, that will drive some kind of image of Libretime to the public.
I think our current logo/colors schema could be improved.

• Name: is not gonna change, but I found many ways to write it : Libretime, LIBRETIME, LibreTime. Which one should we use ? I prefer Libretime.
• Short name: could be LT , lt or LBT , lbt. This is useful for a libretime namespace for example, where want a shorter name. I already saw LT somewhere.
• Color schema: currently orange, I propose to use dark green as primary color #37966f, keep orange as secondary color #fd5523, and use pale/yellowish as bg/fg #fffbe6 (see screenshot below).
• Logo and icon: The current logo is nice, but could be modernized and it follow the color schema.
• Description: I saw "Open Source Broadcasting & Radio Automation - Libretime is an open source radio automation and broadcasting solution helping communities get on-air with ease." and I like this. It can be changed anytime anyway.

I would like to go against the idea that open source project have bad graphics and ergonomics. Building a proper brand will define some guidelines that will help us build consistent and pretty interfaces.

Pretty interfaces are easy to work with, and the human eye likes it.

Docs/Website

There has been a lot of work towards building a nice website and better docs, but I think it was a bad idea to move away from Mkdocs to Jekyll.

• Make a nicer-looking website for LibreTime libretime#1029
• Determine best hosting for LibreTime Tutorials libretime#795
• Project Logo libretime#829
• Add logo to LibreTime Twitter account libretime#898
• Docs: Links are broken on site libretime#986
• Replacing mkdocs with Jekyll libretime#1030
• WIP: Pull the new front page website from ned-kelly libretime#590

Some problems with the current website/docs:

• Jekyll is lacking a lot of features mkdocs already ships, and we now have to maintain the integration of a set of tool (search/syntax highlight/...). Jekyll was chosen to build modern website, but I think mkdocs is totally capable of building a modern website (see screenshot below).
• The current file structure of the docs is difficult to work with, packed a mystic path docs/_docs/* without any hierarchy between the files/guides/how-to/references.
• We maintain multiple documentation, the one for users/administrator in the docs/ folder, another one for contributors/dev/anything in the Github wiki. We should merge this into a single place and close the wiki. This is easier to maintain and requires less effort for finding some information.

An example home page with mkdocs, mkdocs-material and some tweaking:

Marketing

I expect to attract more people to contribute and to use Libretime, by having better/more ways of advertising this project to the world. This advertisement will show that the project is active, this might bring more funding and traction.

Some ideas:

• By having pretty colors/websites/docs/interfaces/logos (see above).
• I saw that Libretime has a twitter account, we should tweet about community meetings and releases.
• An irregular blog could be used to post community meeting recaps, releases, ideas/roadmaps, anything.

All this need time, but we also don't have the tools to reduce the time we need to add/edit something.

I am willing to improve that, but now I need your thoughts about this huge ticket. 😄

[jooola]

I have reworked a bit a logo, we still have the old ideas and I added some to it:

We still have a mic (a different one), an antenna with wave, and the opensource logo blend into it.
https://de.wikipedia.org/wiki/Open_Source_Initiative#/media/Datei:Opensource.svg

This icon and the colors are simpler, and this is better in my opinion.

Any thoughts about this ?

[zklosko]

On the logo: it looks good but perhaps a bit too similar to the Pocketcasts logo: https://www.pocketcasts.com/

On the website backend: how much work did it take to get your screenshot with mkdocs? It looks really nice; a theme update would definitely be welcome for our site. We decided to move to Jekyll from mkdocs because linking, templating, and organizing were difficult with mkdocs. Jekyll does have syntax highlighting plugins we can make use of, although most of the code on our pages is either Bash scripting or assorted config files; neither would strongly benefit from syntax highlighting, but rather an ability to control these parameters from within the UI.

If we're going to change our SSG engine, I'd recommend Hugo or (to keep with our new Vue tooling) Nuxt.js. Keep in mind both of these don't work natively with Github Pages and will require processing time with Github Actions, which will eat into our free credits. Node is fast but not when you're installing a billion packages, and Webpack is sluggish compared to Hugo's Golang library, which would likely compile our site in less than a second instead of Jekyll's 7 seconds (or Webpack's full minute). Hugo also has built-in i18 support.

All this need time, but we also don't have the tools to reduce the time we need to add/edit something.

We'll run into the same issue with Wordpress, a headless CMS, etc., if we don't change our reviewing pipeline. I'm willing to refocus my efforts on documentation/marketing/training/web dev to help speed the process. I'm not as proficient in Node or Vue anyway. 🤷‍♂️

Our search isn't great right now, being a quickly-thrown-together build with Lunr (a fork of Solr). It would be nice to switch to Algolia's free plan, applying for their Open Source discount if needed: https://www.algolia.com/for-open-source/

[jooola]

On the logo: it looks good but perhaps a bit too similar to the Pocketcasts logo: https://www.pocketcasts.com/

IMO, they don't seem to be similar enough to confuse them. The logo can still be reworked a bit tin the direction we prefer.

On the website backend: how much work did it take to get your screenshot with mkdocs? It looks really nice; a theme update would definitely be welcome for our site. We decided to move to Jekyll from mkdocs because linking, templating, and organizing were difficult with mkdocs. Jekyll does have syntax highlighting plugins we can make use of, although most of the code on our pages is either Bash scripting or assorted config files; neither would strongly benefit from syntax highlighting, but rather an ability to control these parameters from within the UI.

It took me a small afternoon for the home page. It isn't hard to tweak a mkdocs theme.

If we're going to change our SSG engine, I'd recommend Hugo or (to keep with our new Vue tooling) Nuxt.js.

We shouldn't plan to create a website from scratch, it is too much work to maintain. We would have to rebuild the search setup, the navigation, versioning, i18n. Using an existing system that already support these feature will let use focus on the content of the documentation. For now I see mkdocs as the best tool for our purpose.

All this need time, but we also don't have the tools to reduce the time we need to add/edit something.
We'll run into the same issue with Wordpress, a headless CMS, etc., if we don't change our reviewing pipeline. I'm willing to refocus my efforts on documentation/marketing/training/web dev to help speed the process. I'm not as proficient in Node or Vue anyway.

I was referring to time required to write content, not how we publish it. Publishing it is actually a bit difficult, but I think this can be solved without any problem.

Our search isn't great right now, being a quickly-thrown-together build with Lunr (a fork of Solr). It would be nice to switch to Algolia's free plan, applying for their Open Source discount if needed: https://www.algolia.com/for-open-source/

Mkdocs is shipping a nice search engine, possibly also based on Lunr. I am against using Algolia, where we can have a search engine out of the box with mkdocs for instance.

[jooola]

This ticket hasn't received much attention from the Libretime maintainers.

But I want to mark this as required for v3. Specially the documentation part.

[jooola]

Progress can be tracked / visualized here https://jooola.github.io/libretime/

[zklosko]

I'm a bit upset that you're willing to throw out all the work I've done with our website instead of reading the Jekyll documentation and trying to add to our current setup. Most of your feedback has to do with the theme, which can be easily updated, and there are plenty of plugins and modules we can use to extend the site in the way you're thinking.

[jooola]

@zklosko I do understand that it is no pleasant to see your own work, being mostly overwritten by someone else. Please note that I did consider keeping Jekyll and building on top of your work.

Still the new website have some underlying problems:

• Time consuming: I don't want to spent too much time on gluing / re inventing features that comes out of the box using mkdocs. And in a really powerful way. Maybe you want to imporve the Jekyll website to have some kind of feature parity with the mkdocs material theme ?
• Complex: The entire website/docs structure is messed up, I mean throwing all the files in a docs/_docs/ is in my opinion not best structure. More layers and directories would be welcomed. Additionally the docs cannot be browsed on GitHub, only on the website.
• Documentation is tightly coupled to the website: The content of the documentation needs a big rewrite but most of the changes I expect to do, requires me to edit some base templates files, as everything is not yet fully automated. We need something less coupled, that one edition does not requires to dive in html templates and such. This allow new comers to be able to edit the documentation without having to learn the structure of the website first.

In other words, we should kiss and dry.

I hope these comments are not too harsh on you, and that you agree with these points ?

[zklosko]

Can you please reference specific code chunks where you believe it would be too difficult to keep Jekyll around?

[jooola]

The points I mentioned above are self explanatory in my opinion. You can disagree and argue about it, but I'd prefer not to enumerate all the things I am not happy with in the current website.

Using material mkdocs does comes with a lot of feature out of the box, and we won't have to worry about it anymore.

[jooola]

@zklosko We haven't reached any agreement yet. How could we sort this out ?

Do you actually agree on the points I mentioned above ?

[zklosko]

I don't believe you've done your research. We can talk more when you better understand the system.

[jooola]

@zklosko I don't know how to answer to such messages, this isn't productive at all. I'll just continue my work on the docs.

[zklosko]

@jooola Sorry for being so rude. After a bit of reflection I see that my comments were out of line. Please forgive me.

You are right that the docs and site haven't aged very well. I'll support the transition back to mkdocs if that's the direction we go.

[jooola]

@zklosko It's all good, I do understand the delicate situation I was putting you into ! I appreciate that you wrote back to this issue to sort it out.

My current focus is on bugfixes and the django API, the docs/website will have to wait.