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

[ninetydegrees]

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

- Any good tutorial explaining how to create a layer (with screencaps)
- Any good tutorial explaining how to create a style (with screencaps)
- Most CSS visual guides.
- This part of the S2 manual although I think it should be fleshed out and give concrete examples of how these are used. I'm not a programmer and figuring out where and how to use these was done by looking at other layers and experimenting.
- As many said, the Core Layer but it could be more useful if we could jump to sections: classes, property groups, functions. I think it needs more comments too.
- The features by layout and layout by feature lists except that they're incomplete because only features from the how_to community are listed.

What did you wish LiveJournal's styles-related documentation had?

Everything else? First, there is no explanation of the jargon and symbols: layer, function, operator, etc. You have to figure everything on your own or with someone's help if you're not familiar with programming languages. Secondly, once you get that each function codes a little part of your layout, you have to find the one you need. They don't always have the same name, some even have obscure names. I wish there was some kind of index where I could look up 'entry', find all the functions coding entries in every layout then go see this particular part of the source code. What really helped me understand how S2 works was by looking at source codes and comparing them.

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?

I can code a layout from scratch but any fancy coding is beyond me. I can use nifty tools others made, even adapt them to my own needs but not create some.
I'd like to make my layers viewable/public by clicking on buttons and I'd like to see a list of public layouts. Sharing code and layers should be as easy as possible.

[ninetydegrees]

!what documentation could Dreamwidth provide to help with transitioning between the two?

One thing I found awesome in DW Core Layer:

# was !view_entry_disabled
property bool use_journalstyle_entry_page { des = "Show entry pages in my journal style rather than the app style"; }

Thanks for the comment. It made it easy to find this.

One thing I also found awesome but am lacking explanations for:

I don't know what are the values for 'grouptype' and what they mean. For example, I know 'viewlist' means check boxes on the same line because I saw it. But it wasn't said and I couldn't guess it by the name. That's what I mean by more comments.