🚀 We are looking for documentation lead 🚀

[kaplanelad]

🚀 Join as Documentation Lead to Loco Core Team 🚀

Hey everyone! 👋
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]

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

_ Lerina

[lerina]

opps I should have signed in with my personal account
_lerina

[jondot]

@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]

@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]

Hey Loco folks 😄

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

[opeolluwa]

@kaplanelad are you still open to a documentation lead?

[kaplanelad]

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

[opeolluwa]

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]

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]

@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]

@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: ✍️ 👋 Guest blog posts #559

WDYT?

[opeolluwa]

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]

@kaplanelad can we carry on with this.

[devartes]

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

[joshka]

@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]

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]

@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]

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]

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

[joshka]

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]

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]

@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

[abdielLopezpy]

Hi @kaplanelad and Loco team 👋,

I am thrilled to apply for the Documentation Lead role. With a passion for creating clear and comprehensive technical documentation and a strong commitment to enhancing user experiences, I am eager to contribute to the growth and success of Loco.

What Can I Bring to the Table?
Technical Documentation Expertise: I have extensive experience working on open-source projects, where I have drafted, organized, and maintained documentation that is both accessible to beginners and valuable to advanced users.
Familiarity with Modern Tools: Proficient in tools such as Markdown, Zola, and various static site generators, I am also skilled in content internationalization, ensuring documentation is accessible to a global audience.
Passion for Rust and Open Source: As a dedicated Rust enthusiast, I am excited to support and promote Rust-based tools within the open-source community, helping Loco become a cornerstone project in the ecosystem.
My Action Plan:
Review and Enhance Existing Documentation:

Conduct a thorough audit of the current documentation to identify gaps, inconsistencies, and areas for improvement.
Ensure all code examples are up-to-date and functional with the latest versions of Loco.
Expand Documentation with Detailed Tutorials and Guides:

Develop comprehensive tutorials and step-by-step guides to facilitate the onboarding of new developers.
Create practical examples and use cases that demonstrate the full capabilities of Loco.
Develop a Strategy for Spanish Translation:

Translate key documents into Spanish to reach a broader, Spanish-speaking audience.
Coordinate with the community to ensure translations are accurate and culturally relevant.
Improve the Existing English Documentation:

Enhance clarity and readability by refining language and structure.
Update outdated sections and incorporate new features as Loco evolves.
Implement a consistent style guide to maintain uniformity across all documentation.
Internationalization and Multilingual Support:
In addition to expanding the documentation in Spanish, I aim to establish a framework that supports multiple languages. This approach ensures that Loco can cater to a diverse global community, making the documentation a truly inclusive resource.

Commitment:
I am dedicated to contributing flexibly and remotely, aligning with the team’s needs and project timelines. My goal is to make Loco’s documentation a powerful and user-friendly resource that empowers developers worldwide.

[mandarvaze]

@kaplanelad

I would like to help with the documentation - work with the documentation lead. (I assume updating documentation is not one person task)

How can I help ?

[kaplanelad]

Hi @mandarvaze,

Thank you for your interest in improving the documentation! It's great to see your enthusiasm to contribute.

To get started, please take a look at this comment for more details: link to the comment.

Additionally, I’ve noticed a lot of valuable discussions happening in both our GitHub Discussions and Discord. Many of these questions are well-answered, but unfortunately, some of this information isn't properly documented, or it could be better organized.

It would be incredibly helpful if we could:

Review the frequently asked questions from Discussions and Discord.
Identify answers that are missing or not well-documented.
Organize or update the documentation to ensure it’s clear and accessible to everyone.
Let me know if this is something you'd like to help with, and feel free to reach out with any questions! 😊

[bionicles]

could it be possible to add a "suggest edit to this doc" link on each of the docs pages? then we could jump more directly from reading to suggesting edits on git

I'd love to see a doc on frontend, it seems the SSR Starter's frontend just points to the fallback page by default

Also having issues getting the mailer SMTP thing working; it might be good to set defaults for SMTP that work by default, even if that's just "stub" mode; perhaps we could potentially guide setup with a few major mail sending services?

just ideas, loco is a brilliant idea for a project! keep it up!

[joelparkerhenderson]

For what it's worth, I maintain documentation for a popular project, including locale translations

There's a write-up of how we do it here, including a directory per locale, and content tracker ids to help translators.

https://github.com/sixarm/locale-help/