🚀 We are looking for documentation lead 🚀

kaplanelad commented 2 months ago

:rocket: Join as Documentation Lead to Loco Core Team :rocket:

Hey everyone! :wave: We're on the lookout for a passionate Documentation Lead to help us take Loco docs to the next level. If you love writing, are detail-oriented, and have a knack for making complex things easy to understand, we’d love to have you on board! Your work will be key in helping developers worldwide use Loco effectively. Contribute on your terms, from anywhere in the world. If you’re excited about making a real difference in the open-source world and Rust -- join us!

atova-agency commented 2 months ago

Hello Elad, I was thinking of starting the french version of the present docs. How may I help with the main documentation?

_ Lerina

lerina commented 2 months ago

opps I should have signed in with my personal account _lerina

jondot commented 2 months ago

@lerina thanks! feel free to do so. Best way to start is with the README, create a pull request for a new language. Then, for each file in the docs, you can create a new file with the translated content:

for example guide.md becomes guide.fr.md

lerina commented 2 months ago

@jondot , hi. Regarding the file structure, I just want to confirm that having "guide.fr.md" implies it should be located in the same directory as guide.md. as in: loco/docs-site/content/guide.md loco/docs-site/content/guide.fr.md

So I don't need to create a new directory such as loco/docs-site/content_fr/

joshua-mo-143 commented 2 months ago

Hey Loco folks :smile:

I'd be happy to jump on board and help with anything that needs patching, docs-wise.

opeolluwa commented 2 months ago

@kaplanelad are you still open to a documentation lead?

kaplanelad commented 1 month ago

@opeolluwa sure Where do you think you could assist us?

opeolluwa commented 1 month ago

You mentioned "taking Loco docs to the next level" I suppose there's an initial work you'd like me to work on,

Otherwise, I'm thinking, full fledged tutorials, YouTube videos, social media content and blogs post, of course one at a time

candidosales commented 1 month ago

Hi @kaplanelad,

I'm interested in contributing to you. I have experience with Astro, and Astro have an excellent tool for documentation. You can check it out here: https://starlight.astro.build/.

It supports:

Site navigation, search, SEO, easy-to-read typography, code highlighting, dark mode and more;
Markdown, Markdoc, and MDX;
Internationalization;

We can create a new repository only for the docs.

I can help with architectural information for the new structure.

kaplanelad commented 1 month ago

@candidosales Starlight is built with JavaScript, we prefer to use Zola for our projects. As avid Rust enthusiasts, we aim to promote and support Rust-based open-source tools.

kaplanelad commented 1 month ago

@opeolluwa From my perspective, the next steps are:

Review the Documentation: Thoroughly read through all documentation to ensure there are no gaps, especially between the instructions and the examples provided.
Test the Implementation: Attempt to implement features using the documentation, ensuring that everything works as described and that no steps are missing.
Enhance the Blog: Improve our blog by adding more articles. You can check out some of our suggested blog post topics here: https://github.com/loco-rs/loco/issues/559

WDYT?

opeolluwa commented 1 month ago

Makes sense!

Let's start with the first thing, that's going over the docs to be sure everything is in order.

As we progress I'll extend to building with Loco, adding more blog posts.

What's more! I'm excited to work on this! 😁

Do you think we have a plan already? @kaplanelad

opeolluwa commented 1 month ago

@kaplanelad can we carry on with this.

devartes commented 1 month ago

That's really cool! I love Rust. If the translation into Portuguese (Brazil) is welcome, I would be happy to help! 😊

joshka commented 1 month ago

@candidosales Starlight is built with JavaScript, we prefer to use Zola for our projects. As avid Rust enthusiasts, we aim to promote and support Rust-based open-source tools.

As a counter data point, we had the same perspective of wanting to find a rust based solution for https://ratatui.rs, which we originally created using mdbook, and then migrated to starlight. We found that it met our needs much better than Zola for a number of reasons. Starlight had a better deployment story (we push and get deployments to cloudflare for free, including automatic preview links on github for each PR). Then there's a wide availability of custom components that are pure npm packages (things like code blocks, rehype, remark plugins for markdown, mermaidjs, ...). One of the big risks we saw in jumping on Zola is that it has a low bus factor (it's pretty much a 1 person show) Compare https://github.com/getzola/zola/graphs/contributors to https://github.com/withastro/astro/graphs/contributors and https://github.com/withastro/starlight/graphs/contributors. Looking back I don't regret choosing starlight over any other framework for doing our docs site. (We looked at and prototyped a few different ones).

The biggest benefit of using markdown is that at least your content is fairly easy to migrate if you do choose to sometime in the future. That means you might find that once Loco is good enough to self-host, perhaps it would be worth using loco to host the loco.rs site?

lerina commented 4 weeks ago

IMHO, Let's focus on cleaning up the doc. It's getting complicated fast. Loco is moving fast :-) Code snips are not in sync with the current version. Tiny discrepancies can put-off new comers as cut and pasting the code may not give the intended result.

The current tech is fine. "Zola is written in Rust and uses the Tera template engine ,.." Perfect for loco people :-) "Content is written in CommonMark, a strongly defined, highly compatible specification of Markdown." source: https://www.getzola.org/documentation/getting-started/overview/

opeolluwa commented 4 weeks ago

@lerina @joshka I'm beginning to think that given the pace at with loco changes, there will be even more rapid changes in the future, in that case there is a need for a framework that can help developers to quickly iterate and update the docs.

whatever framework would be settled for should be "future-proof"

SirMishaa commented 3 weeks ago

I agree with joshka, Starlight really is a good tool for writing documentation.

The current documentation suffers from the same flaws as Ruby on rails, it's very poor, badly organized and doesn't have a navigation bar where you can click easily to see some section.

I think that for scalability reasons, it's a good idea to take a look at how open-source libraries are made, which are used by many developers and which appeal for the quality of their documentation.

In concrete terms, there's this:

Starlight (e.g https://v2.tauri.app/)
Docusaurus (meta is behind) (e.g https://docsearch.algolia.com/docs/what-is-docsearch/)
VitePress (e.g https://phhofm.github.io/upscale/multimodels.html#photo)
MdBook (e.g https://rust-lang.github.io/mdBook/)
a lot more...

It's really important to make a choice that's suitable for a growing community, a format that's easy to modify (markdown), and something that's at least modern with good search and navigation features.

Then we can focus to improve the documentation by giving much more examples, going into details, ...

Sillyvan commented 3 weeks ago

We could also use https://rspress.dev/ with markdown.

joshka commented 2 weeks ago

The biggest "future proof" you can do is just write markdown. There will be challenges to change to other system, but they'll be small changes and mostly automatable. We went from mdbook and quickly outgrew it to starlight, but checked out a few different docs / SSG tools in the process.

I'd suggest checking out the astro / starlight discord - it's popping. We've had really good success asking technical questions and getting rapid answers / solutions to things we wanted to do. And when we submitted PRs they were reviewed and merged fairly quickly too. It just seems like a healthy well run tool. This is because starlight is just a component in a larger astro ecosystem rather than the one tool. Vitepress is probably in a similar boat. I think the main selling point of astro over Vitepress was greater familiarity with the JSX style of apps over Vue's more interesting syntax. YMMV there.

opeolluwa commented 2 weeks ago

Well said @joshka

I've had to migrate Zola to Nuxt Content some time ago, and I can say that the way to go is to use Markdown. And I think we can go on with Starlight, I've heard awesome reviews about it l.

@kaplanelad what's your take on this

Sillyvan commented 2 weeks ago

@candidosales Starlight is built with JavaScript, we prefer to use Zola for our projects. As avid Rust enthusiasts, we aim to promote and support Rust-based open-source tools.

Well that is the take. I mentioned Rspress because i thought it was actually built in rust but its not. Its just their buildchain and mdx compilers that are rust

loco-rs / loco

🚀 We are looking for documentation lead 🚀 #730