I find the
syntax page to lack readability.
When
redoing my own, I went for 2 columns :
* Above is basic info.
* Left is syntax.
* Right is result or explanation.
* Under is extra info.
* Between elements is a horizontal line.
I am happy with it.
----
Now, concision vs verbosity.
DokuWiki supports multiple ways of creating links.
Obviously dokuwiki.org is about DokuWiki.
Obviously the ways are multiple since they are listed right after.
So the whole sentence is useless.
Linking to a specific section is possible, too. Just add the section name behind a hash character as known from HTML. This links to
this Section.
This links to [[syntax#internal|this Section]].
Obviously it's possible since we are doing it right next.
Do we need to name the character ? Probably not.
Wiki's purpose is to not need html, so no need to talk about it.
"section " is said 4 times, let's remove some.
More concise :
You can link to a specific section by adding it's name after a # : This links to
this Section.
This links to [[syntax#internal|this Section]].
Hmm... "section " is still said twice. "link" too.
And we show the example, so no need to describe what is in it.
More concise :
----
Concise or not, such exhaustive page is easily crowded.
Be it view, edit or history.
What I did in a
similar case :
* Move too big sections as sub-pages.
* Make sub-page's title section about the basics.
* Use
include plugin to include said title section in main page.
* Configure plugin to show "Read more..." after said include on main page.
The table and image sections could definitely have arcane details moved out of the way.