foxfirefey (![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png)
foxfirefey) wrote in ![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png)
dw_styles2010-06-13 11:07 am
foxfirefey) wrote in dw_styles2010-06-13 11:07 am
Entry tags:
Ramping up styles documentation
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?
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?
no subject
I'll probably have more relevant comments soon :)
no subject
no subject
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.
no subject
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!
no subject
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...
no subject
no subject
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.
no subject
no subject
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
Any ideas? Or do I need to go post something properly?
no subject
I am a geek. I know HTML inside out, I am -- okay at CSS, and I learned to program C young even if I never actually did much programming. I parse geekish obfuscation quite well. Those damned docs consistently gave me a headache every goddamned time I tried to read them. I wish I were exaggerating. Nope, actual physical pain, every. single. time. I actually had a lot better luck when I started actually just flailing around in the code directly, when I got started here at Dreamwidth. (At the time, there weren't really any styles to be had, as it was early closed beta! I had to troubleshoot why stuff wasn't porting over properly.)
So basically I got nothing but: *POMPOMS* *CHEERS YOU ON!* <3<3<3. Because honestly. You're going to make there be real docs? That don't hurt my head? FEY HOW ARE YOU THIS AWESOME.
no subject
Those comms touch very little on actually helping people understand the language, though, as most of the people asking for help are interested in copy&paste solutions, not deeper understanding. For that I can't think of any great pre-existing docs. My own posts on the topic were more like "isa and as, yay!!!" Most layout help comms do have a tonne of examples of how to apply the language to make awesome things happen, though, so that might be useful reading when writing a cookbook.
(reposted to correct stuff!)
no subject
no subject
no subject
S2 Guide: Troubleshooting
Do you think it'll make sense to people struggling with those darn compiler errors?
no subject
no subject
no subject
no subject
no subject
no subject
no subject
no subject
With other proofreading/editing, I have a number of years' experience (most of it on my own, but I've worked for a couple of other publications as well, mostly as a volunteer/intern), and a degree in Writing and Communications. I can send a resume if you like. :)
no subject
no subject
no subject
no subject
no subject
no subject
It also suffer from a problem of its target audience not matching a good proportion of its actual audience. A lot of the people who want to do styles really aren't programmers, and they need a lot more explanations about basics. There's tons of good beginner documentation out there, but it's scattered far and wide, so unless you know where to go, you can't find it.
no subject
Yeah, that's me, and I'm pretty sure that you're right about it being targeted to people like me. What I did when I wanted to start playing with S2 was sit down, read the manual from the first section through to the last section, and then bookmark the Core Layer 1 appendix for reference. It was an "I want to learn this new programming language" approach, and I know a lot of people have an "I want to produce a style" approach instead and were frustrated as all get out over documentation that was completely not written for that kind of quick language reference. But, having seen that frustration, I somewhat selfishly don't want to flip it around and leave my kind of programmers just as frustrated by the next cycle of documentation.... And I don't think that it would have to, of course: there's a lot of really good technical writing out there that can please -- well, most of the people most of the time, at least!
I'm going to try and think about what made the S2 language particularly easy for me to learn from the old documentation and think about ways in which that can be made a part of the new documentation. I haven't paid much attention to the beginner documentation, because that's not what I needed, but I would like to go back through some of the old lj style comms from the time that S2 was first introduced and see what some of the more common questions and gotchas were for the other programmers learning the language, and see if those can be included in the new manual as well.
no subject
There's also going to be cookbook sections, that try and give programmers and non-programmers alike enough examples to get their feet wet.
Your plan sounds really great! I look forward to your research and deductions.
no subject
What I really like about the MySQL docs* is that it's arranged the same all the way throughout:
1) A quick, full syntax of the command, with options included where they should be and marked as optional, e.g. the SELECT Syntax.
2) And then there's a complete, in-depth explanations of what every single piece of that statement means and how it's used.
Having the full syntax at the top makes a great refresher for experts who just need to learn the site-specific syntax or double-check an option they don't use often, and the complete, in-depth explanations in plain English are useful for beginners just starting out.
Also, "official" cookbook examples should be linked on the doc pages that explain the syntax.
* The newer versions seem to be getting more gobbledygooky and less like they used to be, but they're still a decent enough example for useful documentation. (The Django docs, OTOH, are an example for how not to write useful docs. *rolls eyes*)
no subject
This is me (the "I wanna style" person, that is). Now I am totally up for learning a programming language if that's what it takes, but with LJ's documentation it was hard to know where to even begin. Should I just grab a C or a Java book first? Should I know enough to modify, or should I really get down to the basics and work my way up? Etc.