Cloudron Documentation Ideas

[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.