Documentation questions!

[ysobel]

Now that the styles overhaul is closer to complete, the styles documentation team, led by ysobel, is starting to write up documentation for various aspects of customization, ranging anywhere from basic ("I don't know HTML or CSS or S2 but I want my journal to be pretty, how do I do that?") to complicated ("I want to create a completely custom style, what all is S2 capable of?") and various points in between.

Obviously, this won't all be ready by open beta. However, since a lot of the documentation is being created from scratch anyway, we decided that it would be a good idea to get input from the people who will actually be using said documentation.

So. Please feel free to answer any of the following questions, or provide any other comments that might be useful! We don't promise that everything everyone suggests will be used, but we will listen to what you have to say.

...with one exception, and I probably don't have to make this explicit but am just in case: A lot of the people who are working on Dreamwidth styles and documentation were also involved with LiveJournal support and documentation. This isn't to say that you have to pretend that everything is perfect -- I will be the first to admit that LJ's S2 manual is (shall we say) less than ideal -- but please be respectful of the people on the other side of the screen. :)

(In other words: we want your feedback, because we want Dreamwidth to have Awesome Documentation [tm], but politeness is always appreciated.)

* What aspects of LiveJournal's styles-related documentation did you find particularly good or useful?

* What did you wish LiveJournal's styles-related documentation had? (particularly, what did you have to figure out for yourself, or ask someone else for?)

* What level of customization are you comfortable with, what would you like to be able to do, and what documentation could Dreamwidth provide to help with transitioning between the two?

* Are there (relevant) questions that you have? What (styles-related) things have you always wanted to know? What else do you want to tell us?

Comments

[branchandroot]

User case: I make and alter theme layers and, occasionally, layout layers, usually not from scratch.

The one part I found useful and the thing I used most was not exactly documentation. I think it should be documentation, though.

It's the page for Core that does up all the functions in tables. That was where I found what was associated with what, down in the global functions and classes. Like... what variables do I feed get_url to make it cough up the right url. Or what are the child-functions I can call inside a Comment function.

I go to the public layers area and search the Core table for things like that because I could never make head or tail of the actual documentation. If the little explanation labels in the table could be presented in some similarly contextualized but perhaps not quite so unwieldy and more detailed way, I would find that very useful. Especially some introductory explanations, like what are these class things, and what syntax does one use with them, and what the subclasses of Page are all supposed to be used for, etc., because I had to puzzle out a lot of that by trial and error.

[janinedog]

+1 on the Core layer thing. That's the one page that I always have up if I'm doing S2 work.

The official S2 manual is useful for some things, though. In particular, I use this page a lot. And a lot of the other pages are useful if you're not familiar with S2 syntax. It's just missing a lot of stuff since it wasn't really updated since S2 was first made.

[draigwen]

Ditto what they said. Particularly since there are such a lot of new functions with DW which will make life a helluva lot easier for the style designer.