Proper graphic chart, better docs/website and some marketing #8
Comments
|
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. This icon and the colors are simpler, and this is better in my opinion. Any thoughts about this ? |
|
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.
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/ |
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.
It took me a small afternoon for the home page. It isn't hard to tweak a mkdocs theme.
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.
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.
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. |
|
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. |
|
Progress can be tracked / visualized here https://jooola.github.io/libretime/ |
|
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. |
|
@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:
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 ? |
|
Can you please reference specific code chunks where you believe it would be too difficult to keep Jekyll around? |
|
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. |
|
@zklosko We haven't reached any agreement yet. How could we sort this out ? Do you actually agree on the points I mentioned above ? |
|
I don't believe you've done your research. We can talk more when you better understand the system. |
|
@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. |
|
@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. |
|
@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. |
|
@zklosko I guess you are working on this @ https://github.com/zklosko/libretime/tree/lt-docusarus/docs ? Could you tell us more what your plans are with your work ? Here are already a few questions: I don't know if you read parts of the django documentation, but this software has a great documentation in my opinion. It is a large documentation, and they managed to make it easy to use. See this section https://docs.djangoproject.com/en/4.0/#how-the-documentation-is-organized. We shouldn't try to replicate exactly the same structure, but get some inspiration, and build our own structure. I would be happy to discuss this with you and others. If we use docusaurus for the docs/website/blog, will the documentation also be readable from github ? What do you think about the new color schema I proposed in the description of this issue ? Don't you want to differ from the Airtime theme (flashy orange) ? |
|
Yes, I'm working on it. Yes, I'm open to contributors. Aside opening a PR, I have had issues with collaborating in public repos but I can try. I wasn't intending to open a PR until it was mostly finished. I see what you mean about the Django docs. I take inspiration from the Docusaurus docs themselves: introduction, getting started, guides, advanced guides, specific topics... I've started organizing the docs we have but I've had to do a lot of pruning to remove what's no longer relevant. The general restructure is taking some time and some planning too. Will the docs be readable from Github? All docs will still be written in Markdown and accessible in our source tree, if that's what you're asking. I kept with the orange color schema just as a way to preserve defaults. I'm open to changing the color but that's a very large change across the site, logo, and entire UI that should probably be reserved for a PR of its own. Just focusing on restructuring and switching engines for now. |
Ok I don't want to disturb your work. But in order to prevent too much changes when you're work is almost finished, I would suggest proposing your work to reviews as soon as possible so we can discuss and raise issues before put too much work in it.
I would like to involve other maintainers in the new structure discussion so we all agree on a solid structure. As per above, maybe this can be discussed in reviews ?
I was wondering whether some feature will clutter the markdown files with jsx, for features such as tabs or advanced display components. From what I understand in .mdx files, it will be mixed with some javascript/jsx. Maybe it does not clutter that much the files ? |
|
There isn't a lot of MDX clutter in the docs. The most you might see are tags for tips, warning, and info sections, like so: |
|
I was thinking about https://docusaurus.io/fr/docs/markdown-features/tabs. But maybe I'm being a bit too picky. |
|
@zklosko Any idea when you will be able to open the PR ? I am doing a lot of changes to the configuration schema and installer. I was hoping to start writing some documentation using the new tool ? |
|
I think it would be worth posting releases on Reddit on different related channels. We might gain some visibility with that. Maybe starting once we have a first beta version |
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.
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.
Some problems with the current website/docs:
docs/_docs/*without any hierarchy between the files/guides/how-to/references.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:
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. 😄
The text was updated successfully, but these errors were encountered: