Ramping up styles documentation

[foxfirefey]

Up until now, the biggest homegrown documentation effort for styles has been the S2 CSS docs--which are nice for people trying to modify their styles with CSS, but there's no real cohesive documentation on the S2 system except the old LJ S2 manual. They are the kind of docs that say, and I quote, "The language is very similar to other languages which geeks are already familiar with. The learning curve isn't too steep." And that's the kind of person they're designed for. Unfortunately, for a lot of people, that is a steep learning curve--and we want to try and alleviate that.



So, my current steps to making documentation:

* Fortunately, the functions in layers do have some built in documentation. You can see the auto generated documentation for Core2 (the base of Dreamwidth's S2 system) here, and I've just put in a patch to make the layerbrowser for core2 and other layers more readable. We'll want to make sure all the functions in core2 have documentation that shows up in the layer browser, and that these is reasonably understandable.
* Make a new S2 guide to explain the language at a more starter level, and give people the tools they need to read the function documentation. I have a proposed table of contents
* Also have this S2 guide have a section explaining the backend, for coders who will need to make changes to the back end
* The guide should have lots of coding examples -- that is, all language principles should have explicit instances of code they're used in
* The link to documentation in the advanced customization area should link to this guide, and stop linking to the old LiveJournal documentation
* We probably also want a cookbook, so that some examples are available to show people how to put abstract knowledge to real uses
* I'm trying to add syntax highlighting for S2 to the wiki like it has for other languages, to make the examples more readable; at some point we'll want to make language files for popular editors, too.
* After we have the basics of letting somebody learn the language down, we can move on to defining and documenting best practices--that is, the sorts of things that are good to do as opposed to possible to do.

Are there steps in this plan you'd change? Steps you'd add? What do you need? Who wants to help? Do you have links to awesome references to crib from/emulate, other than the original documentation?

Comments

[matgb]

One other 'bug' I meant to report the other day, the S2 customisation manual is still inked from the advanced area on DW. It goes to an empty apache folder with a CSS style as the only content.

I then completely forgot to report it when I reported the function that doesn't work. Should almost certainly link either here or to the wiki, right?

You have two links going to the layer display, the latter looks like it should link to your patch? Regardless, that is more readable.

Agree on worked examples, I 'fixed' my code for my TITLE tags the other day, by swapping two clauses around, I have no clue why it didn't work before, nor do I really get why it works now, but it finally does, so we're good.

One thing I'm working on is having different styles available as viewing options; SB and I both prefer dark background layouts, but many readers prefer light, want to hardcode a link to that in the base of each post, think I now know what code to use, but it's taken me ages to figure it out.

So yes, overall, agree. Harass me to start contributing, I'm learning it, can write it up as I do, and now election's over want to do useful stuff.

[foxfirefey]

Oh, really, you fixed it? In that case, let me know what you did, and I'll see if I can't fix the main function.

Right now I'm working on doing a first conversion of the old documentation into something a little less...intimidating. That is, combining this and this into something people who aren't programmers might be able to understand.

When I've gotten a decent way in, I'll poke at you and see what suggestions you might have for it!

[matgb]

Ah, no, not that bit, I've got mine now set that on matgb/dw/org the title is globalname | globalsub, but on everything else it's pagename | globalname, ie it's not username, and it's reversed on entry pages, better SEO and usability.

I'd like to have Reading replaced by the stuff in the bug, which is how I figured out it wasn't working.

What I fixed was if thisis friendspage/elseif recentpage. For some reason putting recentpage first meant it didn't work, but putting friendspage first did. No other code was changed. I'm guessing just a random glitch, but...

It's layer 34512, I have no idea how to make it public, and it's currently just a set of my hacks.

All of which goes into my main layout layer, which by complete random chance is s2id=1337...

[foxfirefey]

I'll see what I can do about replacing that link as soon as I get the new docs halfway up to snuff. Does this make any sense to you so far?

[matgb]

Mostly, yes.

But I think I've got it working roughly how I want it anyway, just hit post as you replied:
http://matgb.dreamwidth.org/372682.html

Anyway, 2am, work tomorrow.

Will try to turn what I've learnt into something coherent for docs at some point, trial and error is fun.

[liv]

Handwavy explanation for the clause swapping: the FriendsPage code inherits from RecentPage. The logic is that the reading page is more or less like the recent entries page, with some extra twiddles. So needing to get your else's and if's in the right order isn't a complete coincidence.

[matgb]

OK, before I go open another help post you might explain this as I'm extending the same code.

function Page::print_head_title()
{
if ($this isa FriendsPage) {
print """[title>""" + $this->view_title() + $*text_default_separator + $.global_title + """[/title>\n""";
}
elseif ($this isa RecentPage) {
print """[title>""" + $.global_title + $*text_default_separator + $.global_subtitle + """[/title>\n""";
}
elseif ($this isa TagsPage) {
print """[title>""" + $*text_tags_page_header + $*text_default_separator + $.global_title + """[/title>\n""";
}
else {
print """[title>""" + $this->view_title() + $*text_default_separator + $.global_title + """[/title>\n""";
}
}

I've moved the TagsPage clause up and down, swapped it around and done several other things. The only thing that works is to remove the RecentPage clause completely, but that almost defeats the point. I'm not sure which I want working more, but ideally I'd like both working, as would kake who specifically asked for this.

Any ideas? Or do I need to go post something properly?