How to contribute to documentation?

[nitso]

Hi.

Found some issues in documentation and would like to contribute. I've seen links to alphadoc in forum, checked it.

1. Where to find description or docs for documentation contribution?
2. Is it enough to edit and save my changes using alphadoc?

I.e. there are issues with gantt diagrams on page https://plantuml.com/en/commons
I went here: http://alphadoc.plantuml.com/doc/asciidoc/en/commons and introduced changes. What do I have to do next?

[arnaudroques]

Many thanks for your help in documentation!

1. Where to find description or docs for documentation contribution?

Here is a good start: http://alphadoc.plantuml.com/doc/markdown/en/a_begin_for_this_wiki
Unfortunately, even this metadocumentation needs some improvement: so you can contribute here too :-)

2. Is it enough to edit and save my changes using alphadoc?

Yes, that's enough.
Since alphadoc is available without any login (meaning it's very easy to use for everyone), we have to validate changes from users to avoid spam.
The official website is then published accordingly few days after that.

So your changes will be online tomorrow.

Many thanks again for your help in improving the documentation!

[The-Lum]

Hello @nitso, @arnaudroques and all,

Coincidence, I made the same changes yesterday, to change all @startuml on @startgantt!

But, however don't hesitate to contribute...

Regards.

[sakirtemel]

@arnaudroques would you consider having an alternative / main documentation moved to something like https://docs.antora.org/antora/latest/ ?

The main advantages are, a good search, great navigation(top for chapters, left for topics, right for subtopics(especially this will be helpful in plantuml's documentation)), and overall good layout + fonts. It's based on asciidoc, and alphadocs already have the asciidoc versions.

I just tried rendering http://alphadoc.plantuml.com/doc/asciidoc/en/sequence-diagram and it works good, if there'll be an interest, I'd be happy to make a Proof of Concept based from alphadocs.

[arnaudroques]

would you consider having an alternative / main documentation moved to something like

Maybe as an alternative documentation.
However, we won't move until we find something which brings us:

1. Ability for anyone to contribute without any user/password in few clicks only
2. Support for several wiki dialect (asciidoc, markdown...)
3. Full support for translation (English, German, Spanish...)

We've build alphadoc because we did not find anything that satisfied these three points. We should probably open source alphadoc, but unfortunately we have no time for that.

However, you can make a Proof of Concept based on few pages so that we see the result. We can even imagine implement a full asciidoc export of alphadoc to that we can use antora for website generation.

However, we do not want to disperse and the current priority is to have a first running version of plantuml-wasm as you can imagine :-)

[sakirtemel]

@arnaudroques makes sense, thank you very much for the detailed answer. I also read the previous threads, I agree that simple+multi lingual editor is important.

I was actually finding the need of a docs with a quick navigation in plantuml-wasm(even perhaps to embed it inside), and started to play with the docs after.

So, I made a proof of concept that is fed by alphadoc: https://sakirtemel.github.io/plantuml-alternative-docs/

repo: https://github.com/sakirtemel/plantuml-alternative-docs
mvp features todo: sakirtemel/plantuml-alternative-docs#7

Please let me know what do you think? And maybe some more people would like to be involved in working on this in the community?