The Website: Forbodings Wiki Improvements

[FLOZi]

RE: Headings; Many people used H1 in current wiki because it has a horizontal rule. Mediawiki guidlines suggest H1 should only ever be used as page name at top, H2 for headings (which is what I do, could we have a shot of say, GameDev:UnitDefs?).

I have to say I feel I would also miss the chevrons.

[AF]

Chevrons are not the only way to do headings, and they don't appear to be especially popular in good examples of typography online. They're used here as a crutch for general poor typography.

What we have currently relies on margin-top of all things for our headings and paragraphs and doesn't differentiate subheadings enough from primary headings.

The question is not are the changes perfect, the question is are they an improvement over what we have.

code tags are inline elements, they're not intended for multiple lines of content yet they're misused as block elements.

This is how it's supposed to work:

Code: Select all

<p>This is the <code>Panel</code> constructor:</p>

<pre><code>function Panel(element, canClose, closeHandler) {
  this.element = element;
  this.canClose = canClose;
  this.closeHandler = function () { if (closeHandler) closeHandler() };
}</code></pre>

That code on its own works at the moment is an artefact of bad styling. I would recommend this be changed in the wiki content when seen.

Current todo:

Required

- Remove display:block on the p code css rule
- Reduce and simplify the logo

For post deployment discussion

- Improving headings hierarchy

[FLOZi]

If wiki is updated to latest software we would get

http://www.mediawiki.org/wiki/Extension ... ight_GeSHi

As part of mediawiki 1.21+ and the whole issue around <code> would be moot.


I don't really care if we lose chevrons so long as the hierarchy is clear

[knorke]

What links?

Each links is followed by an arrow-icon:
imo unnessecary, color is enough. (On texts with many links hampers reading flow.)

I don't really care if we lose chevrons so long as the hierarchy is clear

Yes. But imo hierarchy can only be clear with some sort of chevrons/bullet points/other symbols.
For example when the text explains some structure, like how folders are nested:

or a Lua table is also nested, or just contexts that have some sort of "layer" to them.
The > symbols go perfect for such things.

It is like indention of code.

Code: Select all

{ 
  {
    {

If there was only other forms of styling it would not work so good.
Maybe some call it "crutch for general poor typography" - does anyone want to go over all the pages and adjust them? Just so they fit some random styleguide that uses font styling instead of > icon thing, and then in the end the result is not even better?

---
code tags:
The screenshoted page (and basically all others) already use:
<code><pre>bla</pre></code>
or other way around:
<pre><code>bla</code></pre>
Not sure if order matters.

What we have currently relies on margin-top of all things for our headings and paragraphs and doesn't differentiate subheadings enough from primary headings.

I find it very easy to tell differences between headings:

Even if the page is longer, so that one only see part of it at once like:

it is still easy to keep track where/how deep in text structure one is.

For post deployment discussion

No, please not.
Put up a testpage or more screenshots instead. Once it is good deploy it. Do not risk to put something unfinished online and then it just stays like that forever or something.

[SinbadEV]

Each links is followed by an arrow-icon:
imo unnessecary, color is enough. (On texts with many links hampers reading flow.)

Those should only show up for "external" links and the image is there to make it clear you are leaving the current site/wiki.

[Silentwings]

Put up a testpage... Once it is good deploy it. Do not risk to put something unfinished online

This, again.

[AF]

Momentum should be built else we will have stop and starts. The thought of waiting until everything is 100% good and perfect in theory before deploying is unrealistic and a waste of time. If we wait, it will never be deployed. So long as we don't deploy regressions, and nothing is broken that wasn't before.

A good typographic hierarchy employs:

- Headings size
- Heading colour
- Heading capitalisation
- Heading weight
- Heading spacing and margins

None of which are currently employed. Chevrons work because they are the only thing that indicates hierarchy at the moment, not because they are a good solution.

I'd like to make ammendments to the typographic hierarchy in the theme myself, but it is not a requirement for deployment.

So as it currently stands:

Current todo

Required

- Remove display:block on the p code css rule
- Reduce and simplify the logo

For post deployment discussion/wanted

- Improving headings hierarchy
- Chevrons on headings
- arrow icons on external links

I recommend we move to additional threads for the chevrons, heading hierarchy, and arrow icons, and use this thread for what is absolute minimum for the changes to be considered deployable.

The 3 other items are clearly topics of discussion, not fully formed actionable items, and we should discuss them to determine what needs to be done in a second deployment. E.g. should all headings have chevrons? How should they be styled? Are there alternatives to solving the hierarchy problem? ( e.g. a table of contents sidebar like on gitbooks? )

[FLOZi]

Each links is followed by an arrow-icon:
imo unnessecary, color is enough. (On texts with many links hampers reading flow.)

Those should only show up for "external" links and the image is there to make it clear you are leaving the current site/wiki.

Which is imo 'a good thing'(tm) and something lacking in the current.

+1 to the 'feeling' of code-like indentation when dealing with sub headings.

And because it appears people don't read my posts, please go read what I said re: peoples misuse of H1 and <syntaxhighlight> replacing <code><pre>

[knorke]

If icon is only for external links, then it is okay.

So long as we don't deploy regressions, and nothing is broken that wasn't before.

If the page hierarchy thing gets deployed in the way it is on screenshots, and with the font styling, to me that would be broken.
Think a testpage is nothing too unsensible...

Are there alternatives to solving the hierarchy problem?

I do not see any? ("Contents sidebar" is something completly different.)
It seems like looking for solutions to a problem that does not exist.

<syntaxhighlight> replacing <code><pre>

Such things would be a true real improvement.

[AF]

Do we think then that this should be the plan of action next:

1. Merge changes into git master once jKs changes are deployed and tested
2. Deploy to test.springrts.com for further testing and review

This would mean an endorsement that forbodings changes are the desired path forward, give or take some changes that are being discussed. Do we all agree? I'm in discussion to try and get another test server up. The sample databases have empty wikis so it's not ideal

[gajop]

Momentum should be built else we will have stop and starts. The thought of waiting until everything is 100% good and perfect in theory before deploying is unrealistic and a waste of time. If we wait, it will never be deployed. So long as we don't deploy regressions, and nothing is broken that wasn't before.

If you are talking about deploying it on test, then sure, but don't deploy it live. It would be wise to do so even if not a single change was controversial when you do large changes such as this. It should be tried out for at least a week on test.springrts before pushing it live.

EDIT: Seems like we agree on this.

I recommend we move to additional threads for the chevrons, heading hierarchy, and arrow icons, and use this thread for what is absolute minimum for the changes to be considered deployable.

No, please stop making so many threads, it's hard to follow who said what and where

This would mean an endorsement that forbodings changes are the desired path forward, give or take some changes that are being discussed. Do we all agree?

Maybe, but not yet, we should decide once we see it in detail on the test server.

[knorke]

Think if the test wiki is empty, that does not matter that much.
If they allow to be edited then one can just copypaste a few pages and see what they look like.

[FLOZi]

1. No more threads please
2. Deploy jK's changes then (re)implement Forb's work on the test pages. Only question here is whether that is done before or after 'modularisation' as discussed with abma in the other thread
3.

<syntaxhighlight> replacing <code><pre>

Such things would be a true real improvement.

Requires 'only' an update to the wiki software itself, no longer a separate plugin to install. I'm willing to do the leg work of replacing the markup itself in the pages.

[AF]

We should do it before the modularisation changes as those would involve new repositories.

[smoth]

IMO, pages like this one are really well done:
http://springrts.com/wiki/Gamedev:WeaponDefs

[FLOZi]

IMO, pages like this one are really well done:
http://springrts.com/wiki/Gamedev:WeaponDefs

Thanks

One thing that page lacks is a H1 title at the top, as I have started to do on some pages (as and when I touch them)

e.g. http://springrts.com/wiki/Movedefs.lua

[SinbadEV]

How bad would it be to just use the auto-numbering from the TOC?

(apparently it's supported internally:

$wgDefaultUserOptions['numberheadings'] = 1;

)

[AF]

As it's an option it should be easy to activate and deactivate once a better solution is developed.

I approve of the numbered headings fix.

[gajop]

So what's the status of this, when can we see the wiki changes?

[abma]

http://springrts.com/mantis/view.php?id=4374

i hope/it seems seems jk's changes are fixed, not sure if all "big" problems are solved.