[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Fwd: [Season of Docs - Announcements] Announcing Google Season of Docs 2023



On Thu, Jan 19, 2023 at 1:44 AM Holger Levsen <holger@layer-acht.org> wrote:
we spent a lot of time and effort to be able to maintain
src:debian-edu-doc as wiki, including translations,

Probably you did it a long time ago, and maybe there were no better options for documentation at that time. Why not check out the documentation systems that are available today and see whether they are better?
I wrote my own DocBookWiki system 20 years ago, but I don't even think of using it now because there are better options available.

so why would you want to change this? to address what problems, shortcomings,
bugs, ...?

A wiki usually stores the data in a DB (but not all of them, some use plain text). I don't know what is the case for your wiki, but this is fundamentally wrong (one could also say "blasphemous"). Why? Because it does not allow you to use a text editor (like Emacs) for editing the docs. Maybe you could use some tricks, like export them to text files, edit them and import again, but this does not count.

Another reason for switching to a better system might be that the wiki syntax is a general purpose one (usually), it was not meant for the docs. So, it is not as flexible, powerful and versatile as a language that was created specifically for the docs, like AsciiDoc for example, which can be thought of as a wiki syntax for the docs (actually it is compatible with DocBook).
For example, I remember struggling with the current wiki while trying to add a "Warning" or "Tip" admonition.

Versioning might be another reason. Text files can be versioned easily with Git and GitLab. Although the wikis do have some versioning features, I don't think they are as good as Git (unless they use Git under the hood). Their workflow also cannot be as good as that of GitLab (where you make some changes as a proposal, in a merge request, and after they are reviewed and refined, they are merged and applied).

The question can be turned upside down. Can you name any reasons why the documentation system that you are using is better than the ones that are being used nowadays (for example Markdown+MkDocs or AsciiDoc+Antora)? Besides "if it ain't broke, why fix it".

In the end, everything depends on your preferences. A thing that seems like a bug to someone, may seem like a feature to another. If you are happy with the current system, you can keep it.

> - Reorganizing the docs into Installation, Usage, and Development guides.
> Right now everything is in the same manual, but the information about
> development is almost nonexistent, and the usage information is very
> lacking. For example there are no details about how to use Veyon, or
> squidguard, etc. So, this would also require adding some more details to
> the docs, that are already missing.

I dont see why you need to change the format to add this information
to the docs.

https://wiki.debian.org/DebianEdu/Documentation/Bookworm/ - it's a wiki,
please add those infos there.

It is difficult to make even small changes to a wiki editor (on the browser). The difficulty increases with the size of the pages. It becomes a nightmare if you want to reorganize the docs.

But I am sure that you can find people that are willing to work for improving the docs in the existing system, if they are paid a stipend from GSoD for it.

Kind regards,
Dashamir

Reply to: