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