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 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.