Friday, September 6, 2013

New PHP.net designs floating around

Since 2008 there have been numerous efforts to create a new design for www.php.net, all of which have failed - so far.
We've never come as close as two years ago, when the "beta mode" option was added to our website, but we never really got around to finish it.
The "beta design" has even received a lot of makeover compared to what is "beta mode" now.
To make things a little bit more awesome, there is also a new branch called "responsive" which has a lot of changes in it too, especially for manual pages.

Hopefully, one day, we'll actually finish one of these and flip the switch forever.

In the meanwhile, I'm working on retiring my little baby, PhD, as I want to encourage more people to get involved with the overall project, especially the neglected parts like documentations.
It doesn't help anyone to be greeted with a "ohh, btw, you have to have a doctorate to be able to work on the docs" like "almost" is the case with our usage of Docbook - not to mention the fact DocBook isn't exactly the easiest markup format to learn.

I've been a huge advocate of highly semantic markup, and never dreamed that I would want to get rid of Docbook for our documentation.. But now I finally understand.
It must be *simple* to contribute.

Although I have optimised our tooling from taking over a week down to roughly 3minutes, it still isn't good enough. It needs to instant. And we can't reach that point with out current markup. We need to change. Make it simpler. Attract new people. Make it fun to contribute and help out.

To that end I've started working on a tool I call "WTFM", which is a Markdownish renderer..
The goal is to keep some of our smart trickery and simplifications we do in Docbook, just without that massive amount of markup and confusion. There shouldn't be any need to "learn a new format". Just write the docs, click save and you see it rendered instantly. No weirdo wiki markup noone understands, or hundreds of rules to obey.

I haven't exactly finalised the tool, or the actual "non-format format" yet, but the current (pre-alpha has-a-lot-of-bugs) proof-of-concept is running - and to stay true to our "lets make a new design" goals.. It has completely different markup rendering, so I had to create a new CSS for :)


What is your favorite layout so far? You think you can help us finish any of these?
Shamefully enough, getting the website running locally is a huge pain in the ***, but these instructions should take away most of the pain...

Hope to hear from you!


-Hannes

6 comments:

  1. So, "WTFM"? I should warn you that every web site or application I've ever used that had an "f" on its name had eventually reached a phase where the "f" had to be removed due to popular pressure. Seriously. ;-)

    ReplyDelete
    Replies
    1. "Write The Fudging Manual" just sounded so good. Other ideas I had in my head were things like "phoc" ([PH]P D[oc]umentations) .. Got off that idea pretty fast though :]

      Delete
  2. It's very nice and works very quickly, I like that! :)

    I think that the purple bars are too strong, detract from the content and perhaps there's too many dividing lines (box borders, lines between items in the left menu) unnecessarily dividing the page into boxes. Every line -- both explicit (horizontal ruler, border), and implicit (background color change) -- and every design element (headers, underscores) should be used sparingly and only when necessary.

    ReplyDelete
  3. Hye Bjori, have you looked at Asciidoctor [http://asciidoctor.org/]? Sounds a lot like WTFM.

    ReplyDelete
    Replies
    1. I did see it, but since we can't embed it I stopped looking at it.
      I don't want to pre-render pages anymore, I want them rendered on-the-fly (with certain exceptions)

      Delete