dw_styles | Documentation questions!

Entry tags:

documentation

Documentation questions!

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?

Flat | Top-Level Comments Only

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.

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

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.

Is input useful from someone who never actually looked at documentation but wrangled styles with the help of other users and communities? (e.g.

kunzite1 and various s2_$layoutname, etc.)

Probably.

...that is. If you would potentially use DW's style-related documentation, then yes; the purpose of this is to make said documentation, and it helps knowing what people would find useful. If you would probably not, then maybe yes anyway; there are probably other people that would still like to have the information and would turn to official sources.

I probably wouldn't really use the DW style docs much myself, as I tend to settle for using styles "out of the box" or themes for styles written by other people. When I've messed with styles myself, I've used the explicit tutorials written by k1 and the like, such as this kind of thing, which I found to be immensely more helpful than the LJ style docs. I don't know if that's helpful at all :/

For editing at the CSS level, I think guides like this (http://community.livejournal.com/s2_bloggish/3738.html) are helpful, with diagrams showing which part of the page the classes/ids will affect. A visual demonstration makes it less scary for people who are trying customizing for the first time.

If this is an opportunity to ask style-related questions, I have one: am I correct in assuming that the entries displayed on a tag-specific page (all entries for tag "polka", for example) come through the same method call as the recent entries page, but it's the view the method is called from that changes which entries are returned? Also, will this functionality change down the road if Dreamwidth implements a way to search with multiple tags (that is, return entries with tags "polka" AND "dance")?

I second the recommendation for those visual CSS guides. They are a Godsend.

+1 about the visual style guides. Guides, such as those offered by scotchsour at Insane Journal, or Gossymer at LJ for Layers and Styles gave much simpler, step by step instructions. I found they were more helpful that Official channels, probably because of the language used.

This.

I don't actually care enough about my layout beyond "does it make my eyes bleed? No? Okay then" to spend very much time tinkering, so I'm likely not the target of this question (and also, you know, I've been here for like five minutes), but one of the things I have repeatedly found myself thinking about the LJ documentation on those rare occasions that I have wanted to alter something for, say, a comm layout, was that I really wanted any given pre-made layout to come with a literal picture of which elements were altered by changing what, possibly in the form of something like a screenshot(s) of a page with little mouseover pop-ups or other diagram (arrows) that display the name of the element/class/id/whatever, since IME the approach is "here is the thing I don't like, and I don't know what it's called to look for it and fix it" at least as often as "what all will happen if I change this thing?"

Generally speaking, once I have found whatever element it is I care about changing, the name makes okay sense and all, but as is true any time one is playing with a system one didn't design, another person's naming logic or organization isn't necessarily intuitive.

This.

I could never have got anywhere in Expressive without the diagramatic layout, and it's been useful to point others there as well.

A visual guide combined with a basic walkthrough would be very helpful for most--many of my very tech-savvy friends are still very wary around CSS, which I find so much easier than anything else I've learnt, so simple things like "find the .main bit of the sheet and change the colour to your preferred" to get this result would be very helpful.

I wrote this entry about me & styles, which I know you've already seen, but I'm linking it here so it's easily findable. :)

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

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.

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

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.

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.

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.

I agree with the above comments about style CSS guides. I've heard talks about how Dreamwidth will including an id class for every function/feature for each style so users can customize their layout to the littlest details? But that will sort of be useless if the average users don't know which id class corresponds with which function/feature or what each id class does.

Also, I found one of the biggest problems concerning customizing journal style that most users had is that they don't know where to start and I wrote a guide once about it (outdated now): Where To Start: Jane's Informal Newbie's Guide To Choosing and Customizing Your Journal Layout - http://wistfuljane.livejournal.com/200761.html. So I think, to start, Dreamwidth's styles documentation should at least dedicate one section to style jargons, ironing out what the various jargons will mean. What do we mean by theme? Layer? Style? Because I found the changing/interchanging jargons at LiveJournal to be confusing at times and frustrating when I want to refer to one thing and unable to grasp the appropriate term.

Also, another section on explaining the various customize journal style interfaces, e.g. Select Journal Style, Customize your theme, Edit Your Theme Layer/Advanced Customizations, and what interface does/allow you to do.

Can I also mention how the styles are categorized in Select Journal Style to be the least intuitive? If possible, I would suggest they be reorganized by width > flexible width, fixed width; columns > one column, two columns (sidebar), three columns (2 sidebars), color > white, black, red, blue, green, etc.; available unique options > um, I don't know enough about Dreamwidth's styles to comment; theme (for lack of better word) > holiday, minimalism, writing, photo, etc.

Otherwise, I would suggest another section dedicated to having a brief description on each style, because LiveJournal's original style preview was not really helpful, I don't think.

Having tinkered around with style customizations, I would suggest some other categories for styles: sidebar > left, right, bottom; available unique options > collapsible entries.

The customizations themselves. I'm using Zesty and I'm confused about some of the options under Text. Basically, anything after Title that goes in the HTML concerning comments and including the quoted option and this: Non-linked reply link text. %1 is replaced with the link. What do they do?

Also, note: I think the options to set # of journal entries under Miscellaneous repeats those under Basic Options?

Zesty was committed before it went through the cleanup by the Styles team, so it hasn't been standardized yet -- the options are rather obscure. (I actually don't even know what that means myself, heh.)

Oh, okay. Hopefully, the options will make more sense once it has been standardized then. =)

When working with LJ design customization I mainly stayed with the S2 unstyled expressive theme and went from there.

Documentation that I relied heavily upon came from http://community.livejournal.com/s2expressive/

I particularly made large use of the visual guide to ID's.

What always threw me was all the containers. I've got a better handle on that, but it is still hard to know what will affect what, based on parent/child parameters.

Also, custom layers. I saw a lot of people wanting the same features that required a personal style layer to take care of it (ie hierarchical tag display). I never understood why each individual user had to copy the code into their own layer, it seemed like users should have been able to share that.

I think I used that community more than I used the LJ documentation, because it was more organized, and of course LJ's doc was very limited, and didn't give feedback.

I am something of an odd duck in that I found the official S2 documentation quite helpful! (Perhaps relatedly, I was developing styles in S1 for long enough to get very frustrated by its limitations, so S2 was dramatic and exciting when it rolled out and I have fond memories of that time period.... I'm also a code monkey and more comfortable building a style from scratch (that is, up from the core) than modifying an existing style.)

The Core Layer 1: Classes page was my base reference page for a long time. Eventually the core changed faster than it was documented there and keeping the core style in front of me was the only way to find things, but the documentation in that original page was nice and straightforward.

The language reference was very simplistic, but as a short presentation of what programming elements were available in S2 it did its job well enough. I don't mind that it was a little chatty.

The Core Layer 1: Date Formats was the only place where I felt a lack of examples slowed me down.

Looking through my old LJ memories, most of my questions revolved around the keys to associative arrays such as Comment.metadata and get_link.

Here are some early reactions to S2 and its documentation/lack thereof:
* http://community.livejournal.com/lj_style/168530.html
* http://community.livejournal.com/s2styles/81965.html
* http://community.livejournal.com/lj_style/277633.html
* http://community.livejournal.com/lj_style/172970.html
* http://community.livejournal.com/lj_style/228111.html

Apart from the visual layout of elements mentioned above, what I found most lacking was a walktrhough of getting started hacking S2.

I just could not get my head around what I was supposed to do, I didn't know what "create a new layer" meant, etc.

So something that allows people to copy a core layer into the editor to create their own would be very useful.

Combine that with a list of most useful S2 code terms and how/what they're used for, and a clearer definition of what layers actually are.

I'm now comfortable with the basics of hacking S2, I've completely redone my CSS and taught others how to do it (theirs are always prettier than mine).

But what I'd like to do is create my own, fairly basic, custom layout from scratch--ideally I want all my sites, whether HTML, Wordpress, Joomla or LJ/Dreamwidth powered, to look fairly similar--and have the same stylesheet. So I'd like to know how to take a basic HTML template and then turn it into an S2 layer, in a way that I can define the names for my IDs, CLASSes, etc.

A very basic walkthrough of what a layer needs, what order to put it in, etc that's easily accessible would be very helpful, and open up a lot of potential for new designs and similar.

I've always wanted a way to embed my lastfm widget in the sidebar! LJ's docs aren't particularly well-organised, but I've never had trouble decoding them once I figured out where to put the CSS.

The other thing that I think should be thoroughly documented is how to change the little baldy-guy - userinfo icons, community and feed icons, and privacy settings icons. That was really spotty on lj - easy in some styles and impossible in others. But very rewarding.

Hi. Big open question...

I have always hoped for clear markup and accessible CSS that makes total design possible like Dave Shea's 'Zen Garden'.

Do you think that could be achievable on Dreamwidth?

Yes. :)

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.

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

* 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?)

LJ has many public styles, but non that are completely re-customizable. There were always elements that were unreachable.

There seemed to be no list of all the elements that could be set. And those elements that had to be CSS styled. (I guess because all the layouts were different.)

Although I am happy with writing HTML and CSS, on LJ I ended up with a sort of hotch potch of code. Perhaps this was my own fault, but the (official) documentation was hard to get through, and then you wondered where it all fitted. Then there was LJ version of javascript to tweak until something worked.

I know there were a lot of good people who spent time working out the CSS for each element of certain layout styles and documenting it all for others. But I think that reflected the fact that the official documentation took a lot of time and attention to tackle.

* 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'm really interested in customizing layouts completely, but having the markup in easily accessable CSS elements to do this.

I'm wishing for one (very basic) layout that was constructed so that all the elements could be completely re-designed and accessed via CSS in a theme layer.

I'm really interested in this, and understanding more about how the layers/set parameters work. So I'm really interested in what Dreamwidth can do to make layout design more accessable.

*hopes someone will have the time to drop me a reply*

The styles team (as a whole) is working on making the style system a lot better. Making sure everything has CSS classes, so that people can do CSS-only customization; making sure that those classes, as well as the options available for changing through the wizard interface, are standardized across all layouts; etc. (One of the nice things about the latter is that people don't have to go "well I don't like this layout but it's the only one that offers feature X"; we're separating functionality from appearance as much as possible, and giving users a lot of control over appearance.)

So yes, there definitely will be at least one style that can be easily customized with CSS. And one of my first priorities with styles documentation is to get the CSS stuff down -- what classes control what areas -- since that's the most accessible to most users. :)

I'm okay for some CSS tinkering, having learned most of what I know through lj communities with a lot of asking around on comms and a lot of trial and error. Theme layers still scare me a little :p

For CSS editing, I second/third the guide stuff. Life would be so much easier if we knew what did what. Also a clean CSS template for the different styles so people can do it from scratch. I found one of those somewhere on lj, and it was a godsend. ^.^

Flat | Top-Level Comments Only

Documentation questions!

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject