Documentation structure and clarity

Question

------
For those new to this software it would be good to include a simple overview of the process on the home page.  I suggest something like this:

1. Make a file containing PlantUML commands, either with an editor or when running other software which calls PlantUML.
2. Run (or have the software call) PlantUML with this file as input.  The output is an image, which either appears in the other software, or is written to an image file on disk.

------
On the "Running Page" the phrase "To launch diagram's images generation..." is confusing English.  You could say something like, "To get PlantUML to make an image of your diagram..."
------
On the "Running Page", the number of links is overwhelming. it would be good to make a new section (above the others) named something like "Quickstart to test PlantUML on your system" containing:
    
    Linux
       which will have links to information contained in
            http://plantuml.com/faqinstall.html
            http://plantuml.com/gui.html
    Windows
       which will have the appropriate links
    etc.
    
I say this because I had to do a lot of searching and digging to find out how to test it on my Linux system.

Thank you

Answer 1

First, thanks for your contribution and your suggestion.

We know that the website is not very clear, so we make some slight change.

First, we've added a "Getting started" page ( http://plantuml.com/starting.html ) that first users may found useful. We resuse your text here, hoping that it's fine to you.

Then, we remove from "Running" page the information that are on "Getting started" page.

There are still too many links on the "running page", but we did not find a nice solution to that point. Splitting this page in several pages may be a solution...

Suggestions still welcome!

Comments

Big improvement!  Now if you would just replace the text on http://plantuml.com/starting.html with the following, I'd be _really_ happy! I think beginners would appreciate it.



You can also include PlantUML into your own scripts or documentation tools.
A simple example:

    Make a file containing PlantUML commands, either with an editor or when running other software which calls PlantUML.
    
                Here is a file called "sequenceDiagram.txt":

                        @startuml
                        Alice -> Bob: test
                        @enduml
    
    Run (or have the software call) PlantUML with this file as input. The output is an image, which either appears in the other software, or is written to an image file on disk.

                For example,
                            
                           java -jar plantuml.jar sequenceDiagram.txt
   
            and the result is a nice diagram in "sequenceDiagram.png".

---

It's done.
We should probably provide a way (wiki?) for user to improve the documentation. This is somewhere in the todo list...
In the meanwhile, you can post comments here.
Thanks again!

---

Great--nice job!