Suggestions for documentation improvements and migration

[rollniak]

Hello,

I have some suggestions to help with the documentation migration from bsdstore.ru to cbsd.io and in general.

Here some suggestions. :)

• Write down ours needs. @olevole has already started this with the issue on the CBSD repo.
• Select the right tools for the job based on our need.
  I have found some limitation with mkdocs (e.g: code blocks cannot be nested inside an admonition, I don't have this issue with asciidoc on Jekyll, I don't know how behave ReStructuredText in this kind of situation.).
  Also if, I don't think mkdocs has no multilingual support, maybe am I wrong ?
• Maybe we could write a ROADMAP for the migration from bsdstore.re to bsd.io?
• Write a convention for the documentation (e.g: FreeBSD Handbook, OpenSuse Reference Book )
  This will facilitate the team work, everybody know how the documentation is written.
• We should use text based tools to create diagrams or others tools available for everyone like I explained in the issue Facilitate diagrams modifications and creations for contributors #24.
• We should use code block as much as possible instead of screenshots.
• Start the migration with some advices on how to write documentation withdocumentation guide
• Stop updating the cbsd-wwwdoc repo for the documentation.
  Push update directly on cbsd.io repo. I think it is better to update is
• Centralized the documentation for every language in a single repo.
• It's easier to track change and push some a translation afterward
• Maybe one day we will apply to a Season of docs ?

It is lot of ideas and I'm open to your feedback. I may need some guidance since I'm new in the project. :)

[mekanix]

I'm curious about second bullet. Do you have some other tool in mind? And yes, mkdocs doesn't have multilingual support.

[rollniak]

To be honest it's difficult to say right now. It's important to choose the tools for our needs but it's also important to know the people who are going to work with it. e.g: having a tool written in a language nobody know imply a learning curve impossible to pass depending on the time we have.

I also need to know if your requirements as changed since the issue written by @olevole. :)

I already got a problem when I tried to add an admonition on between line 117 and 131 on the bhyve with dhcpd tutorial with code block nested in it. I'm not an huge fan of Markdown in the case of a documentation project like CBSD

Another Markup Language we can think of is reStructuredRext which is used with sphinx. I don't used them for years and I should try out to see how the CBSD documentation could be rendered.

I personally prefer ASCIIDoc as a Markup language for a documentation like this. I don't get the problem I mentioned earlier with it on Jekyll.
The FreeBSD community show us a good use case of ASCIIDoc + Hugo with the FreeBSD handbook. We also have Antora but it doesn't have multilingual support out of the box and I never tried it.
I know that Jekyll has a non native support of ASCIIDoc support and some plugins for internalization.

---

Based on the @olevole mentioned earlier, the multilingual part can be see as a tree like this:

I presume the 12.X is going to be deprecated in a year and an half. So we can focus only on the 13.X and point out to the old documentation in meantime. On the old website we can point to cbsd.io for 13.X and newer version of cbsd. If we finish the migration earlier then maybe we could also migrate the 12.X on cbsd.io.

---

Here another resource about writing modular documentation

[olevole]

@rollniak > Stop updating the cbsd-wwwdoc repo for the documentation.

The two main reasons why the old repository is still being updated are:

1. the new site is still missing a lot of content from the old site - this causes update problems on two sites at the same time.
2. we cannot transfer 70% of the content because the new engine does not support multilingualism. I still want to support it.

[mekanix]

1. which content? let me work on that.
2. is actually not a problem, we can just have dir for en/ru.

[mekanix]

@olevole ping

[olevole]

The new site seems to be missing a few big articles and some updates (besides the complete absence of the ru part).
Unfortunately, next month I will be very busy, sorry!

[mekanix]

Could you point at what's missing in English docs? Do we need anything besides ru? I've seen de, for example.