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

[axiom_of_stripe]

As, apparently, one of the few people in the world who actually enjoyed the original S2 documentation, I'd kind of like to help with this! I don't have any good links to hand, but I'll see what I can turn up....

[foxfirefey]

Having pored over the original documentation quite a lot over the past few days while I try to make a first effort, I can say it's a very good start if you're pretty good with programming languages. And I don't mean, oh, hey, you can code some, I mean, you know what object oriented programming is, what a static typed language is, what's a shallow copy of an array, you're learn several programming languages and know or can deduce what's behind the handwaving. Additionally, it's severely hampered by format. Most of the pages are really short, and that makes it hard to scan for anything. I've also found that the grouping of information can be strange sometimes--when I make several passes, I accumulate information that I want to gather together in one area. I also sometimes split things apart--if I haven't talked about classes yet, I don't want to talk about how to access variable members of a class.

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.

[axiom_of_stripe]

And I don't mean, oh, hey, you can code some, I mean, you know what object oriented programming is, what a static typed language is, what's a shallow copy of an array, you're learn several programming languages and know or can deduce what's behind the handwaving.

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.

[foxfirefey]

My current plan is I have a language tutorial that pretty much is going to go over everything somebody's going to need to know to read S2 code. It tries to write thing in as basic a level as possible, but there's totally still enough for a programmer to get enough about the language to know what's going on, too. I'll also make a language reference that'll be that kind of a quick know-what-you're-doing scan kind of document.

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.

[aithine]

Suggestion for the docs to make them useful for experts and newbies alike, without having to separate them out according to level:

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*)

[whatistigerbalm]

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.

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.