Cloudron Documentation Ideas

[LoudLemur]

This thread is started in the hope of generating some suggestions for ways to improve Cloudron's documentation.

One of the advantages of Cloudron is that one usually has the solution to one's difficulties already explained in the documentation. This thread's focus is how to improve the appearance and clarity of documentation. For example, some policies on how to create a "How to" example might be useful. One could add a policy that a screenshot or animated GIF of the desktop might be included. Or one might have a suggestion about which colour theme to use, such as Atom One Dark.

If you have some ideas, please throw them into the thread.

[LoudLemur]

Here are some examples of colour themes for the terminal. I like these because they make it somewhat easier to determine which parts are the prompt and which are instructions etc.

https://highlightjs.org/static/demo/

Atom One Dark

16 Solarized Dark

Monokai

[LoudLemur]

There are some organizations which focus on documentation:

Docusaurus 2.0 is out today. It has been completely rewritten.
https://docusaurus.io/docs/markdown-features/code-blocks#theming

There is also readthedocs:
https://docs.readthedocs.io/
https://www.doxygen.nl/manual/faq.html

[LoudLemur]

Different frameworks have different appearances for their documentation. Here are some examples. I like the dark backgrounds, as they help save the planet (less power required) and also are better at night than looking at a bright white page.

Django https://docs.djangoproject.com/en/4.2/intro/install/

ReactJS https://react.dev/learn

TensorFlow https://www.tensorflow.org/tutorials/quickstart/beginner

Laravel https://laravel.com/docs/10.x

[LoudLemur]

Docusaurus has a page showcasing some beautifully made documentation sites:
https://docusaurus.io/showcase?tags=favorite

I browsed through some of the beautiful documentation there and found this lovely example:
https://wiki.iota.org/tutorials/create-nft-with-wallet-lib

[LoudLemur]

Could we support Docusaurus as an application on Cloudron?

https://github.com/facebook/docusaurus

[LoudLemur]

There is Gitbook, too:
https://www.gitbook.com/

which has a gallery of sites made using Gitbook:
https://www.gitbook.com/gitbook-library

If you are familiar with RocketChat's or Cal.com's documentation, they are featured there.

[timconsidine]

@LoudLemur how needed is this ?
I find Cloudron documentation fine in its current form

[nebulon]

@LoudLemur seems like gitbook is a service. Also for the organization we prefer to selfhost as much as possible.

[necrevistonnezr]

@timconsidine We could have avoided a whole thread about a bitwarden cli command with clearer documentation - as in, write it for someone who has never used the tool

[timconsidine]

@necrevistonnezr missed that one
but isn't that a content issue rather than a platform choice?

I don't mind about platform. Content and clarity are key.

[LoudLemur]

@timconsidine said in Cloudron Documentation Ideas:

I don't mind about platform. Content and clarity are key.

I think in this case, platform choices (the colour theme for the CLI on Cloudron) contributed to the problem of clarity.

Documentation policy is also part of the platform, too. For example, one policy that might be beneficial would be to include a worked example for CLI commands. Another might be to include an animated GIF with the tutorial, as pictures tell a thousand words, can be quicker to create than typing out the documentation, and show the entire, uninterrupted flow, so nothing is overlooked in the process.

If we start examining policy, then we might as well look at other aspects of policy too, such as making the display look ok at night, when there is low light and we don't want blue -light to disturnb our sleep cycles, etc.

[LoudLemur]

@timconsidine said in Cloudron Documentation Ideas:

I find Cloudron documentation fine in its current form

Cloudron has good quality documentation, I agree.