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

[principia]

* 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've not built any styles from scratch, but I've done a fair amount of tweaking to some of the basic LJ styles like Smooth Sailing.

I would like to be able to do the following tweaks to any and all styles:

Typeface control

I should be able to dictate what typeface is used for each element in the style, and also the size and color for each text element.

Color control

I should be able to change the color for each element in the style, even if it's a color replacement/hue shift rather than controlling each slice in a gradient graphic.

Width of the window

I should be able to widen or narrow each section of the page individually, to an exact pixel measurement. I think this one is especially key with the widespread usage of netbooks nowadays.

Header graphics

It should be easy to drop custom graphics into the header, and a function for automatic resizing should be available.

Things that should not require manual customization, but should be option settings

All of the customary tag display choices should be available to every style, including options for traditional lists, lists with sections (i.e., automated headers as have been discussed in the mailing list), and tag clouds.

Turning on or off things like embedded content, link previews, and LoudTwitter outputs.

------------------------------

To be honest, I've found LJ's style documentation so useless that I don't know how much of a transition would be needed: DW can basically start from scratch. Anything I've ever had to do I've either figured out myself, or asked someone else who had had to figure it out for themselves.

[principia]

To be honest, I've found LJ's style documentation so useless that I don't know how much of a transition would be needed: DW can basically start from scratch. Anything I've ever had to do I've either figured out myself, or asked someone else who had had to figure it out for themselves.

To be fair, part of the reason for this is that LJ's organization of its documentation for anything is so labyrinthine that it's difficult to find everything (or sometimes, anything) you need to accomplish any given task. That, combined with the lacking search function, made it difficult for me to find the information back when I was doing my customizations.

[ysobel]

To be honest, I've found LJ's style documentation so useless that I don't know how much of a transition would be needed: DW can basically start from scratch.

DW is starting from scratch. *grin* The transition I was referring to was between "what you can do" and "what you want to do". (r/th between the two sites -- there will be documentation on the differences between core1, which LJ's using, and core2, which we've got, but that's probably about it as far as cross-site documentation.)

Part of what I'm doing, which may not have been entirely clear, is figuring out what sorts of things need documentation. Knowing that lots of people have had to figure out X on their own, or ask someone about Y, or never known about Z until someone told them, helps me figure out that X and Y and Z should be in the documentation.

Ideally, I want the documentation to be comprehensive enough that people can find what they want in the official documentation. Not that they will have to use it -- there will still be a lot of people-teaching-other-people going on, I'm sure -- but that they can.

(...and can find it. heh.)

[principia]

The transition I was referring to was between "what you can do" and "what you want to do".

I believe this would be covered by documentation explaining where the new settings are located. The level of theme customization currently available for only a few themes/styles such as the aforementioned Smooth Sailing should be available for all themes/styles. Assuming the Customize Journal Style is going to approximate what exists on LJ, something telling people 'Hey, on these styles/themes you may now implement the following additional customizations, and here's where they're located,' should suffice for most people's purposes. With perhaps a shot or two saying 'You can now go from this (old screenshot of a previously fixed-format theme) to this (new screenshot with rejiggered colors and typefaces) by going here (Customize Journal Style).'

What might be most helpful to the uninitiated is a series of screenshots, diagrammed to indicate which element is being described by what term, so you know what you're changing when you start fiddling with the colors or typefaces.

[montanaharper]

What might be most helpful to the uninitiated is a series of screenshots, diagrammed to indicate which element is being described by what term, so you know what you're changing when you start fiddling with the colors or typefaces.

^^^^
This.

Most of my customization on LJ has been done by using a style someone else has customized via CSS, but the tweaks I've done on my own have all been the result of hours and hours of trial and error with making new layers and tweaking existing code and trying to figure out how to bend the Core style to my will (example: in a previous layout incarnation, I wanted the sidebar on all pages except my flist view).

I imagine the S2 FAQs on LJ are good references for people who know what they're doing, but they're not at all helpful for a complete novice. Don't know if you want to make the effort to teach people how to design/customize DW styles outside of a menu-driven customization interface, though, and lack of basic tutorials wouldn't be make-or-break for me on switching from LJ to DW.

[wntrmun.livejournal.com]

I imagine the S2 FAQs on LJ are good references for people who know what they're doing, but they're not at all helpful for a complete novice.

I completely agree! I simply gave up doing anything different to my journal because I just didn't want to spend the hours trying to figure out how to get it exactly the way I want. I would much rather be spending those hours doing something else. I'll be honest, I'm not one of those computer savvy people-I'm more on the 'operator only' end of things. So I'm all for anything that's going to make it easier for me.

The screenshot idea sounds great! Visual references are always helpful. And if DW needs someone to test the tutorial on it, let me know. I've never made a layout or layer in my life and know nothing of programming (so if I can figure it then anybody can). I've been wondering how I can help out since I lack the computer skills...

Though I will also agree that if this doesn't happen it won't have an impact on my switch to DW. As it is now, I'm not using my LJ for anything but keeping track of people/communities as I'm holding out for DW.