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