foxfirefey: Dreamwidth: social content with dimension. (dreamwidth)
[personal profile] foxfirefey
So, as a recap after about a week of work, there are now two main documentation bodies springing up for S2. I think there's currently enough space both for beginner and more advanced level documentation within those two sets.

S2 Guide: The Language Tutorial is filling out nicely as a first draft. However, the more I work at it in its current state, the more I think it's going to need to be rearranged for better flow at teaching beginners. The Style System Overview has a little bit of content, but is still kind of clunky. But the Troubleshooting section has some pretty awesome stuff right now, if I do say so myself. Haven't yet started on the Core2 Overview, Backend, Glossary, or Language Reference (a more concise version of the Language Tutorial, for cheatsheet checking or referral by people who already know programming).

S2 Cookbook: This starts out with a testbed layout that lets people have a really simple environment to test out code bits. A couple example pages starting to get filled in are strings and on Dates.

Other miscellanea:

* [personal profile] matgb has pointed out that the advanced page points to defunct documentation URLs. What's worse, the layout editor does, too. Hopefully we can point it at the S2 guide instead, or the core2 layer documentation.
* Doing this documentation has also given me several ideas for built in functions to add. For instance, S2 has a split function for strings, but no "join" function for string arrays. Why is there no join function! Does anybody have any input on that?
* Some people have already been diving in to tweaking and editing! Thank you [personal profile] murklins and [personal profile] azurelunatic for your assistance. And thank you everybody who gave your input on the last post on this topic!
* [personal profile] ninetydegrees has some suggestions up regarding this area: Your Layers page: redesign layers table as a tree , Styles: Add links to Your Layers, and Improve the S2 Compiler. They're making me think that instead of wee changes, each area should just go through a redesign. What do you envision the advanced customization area operating like?
foxfirefey: Dreamwidth: social content with dimension. (dreamwidth)
[personal profile] foxfirefey
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.

On with the show )

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?
ysobel: (Default)
[personal profile] ysobel
Very soon*, there will be a stable** version of Core2 available on Dreamwidth. Which is totally awesome (*sends lots of cookies to the styles team*) and means that people can start customizing their journals more!

...it also means that we can start the process of documenting, so people know what's customizable and how to do it. Some of the things I'm planning are on a "would be nice eventually but not priority" list, but some of the things ... need to be done as soon as possible.***

Specifically, and pretty much in order of priority, we want to have:

1) CSS documentation (what classes are available in core2 / system styles)

2) Properties, aka the things that can be set through the wizard

3) Functions, part the first: Core2 functions that are specifically designed to be overridable by style writers

In all cases, these will have descriptions along with each item: not just listing what exists, but describing what it does.

If you would like to help, please comment to this post with:

* your name
* your email (or a way to contact you)
* which of the three area(s) you are comfortable with.

You don't need to know everything, I promise! (Styles docwork, like a lot of the rest of Dreamwidth, operates under the principle that a bunch of people working on a project is kind of like putting together a jigsaw puzzle; you have one piece, someone else has the one next to it, and so on.) It's fine to list more than one (especially since probably anyone who can figure out functions can also figure out properties) or to list all three or to only list one. Mainly, I don't want to have a CSS-only person working on raw S2 code (or, y'know, end up with someone who can translate S2 but doesn't know CSS all that well going wtf at the list of CSS classes).

<3

#

Footnotes:

* with the next major code push. in theory, at least.

** the current version is unstable, which you probably have noticed if you've used it at all.

***By magic, preferably, but unfortunately that's not an option.
ysobel: (Default)
[personal profile] ysobel
Now that the styles overhaul is closer to complete, the styles documentation team, led by [personal profile] 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?

Profile

Dreamwidth Styles

Resources for creating layouts

August 2014

S M T W T F S
     12
3456789
10111213141516
17 181920212223
24252627282930
31      

Syndicate

RSS Atom

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Oct. 18th, 2017 12:42 pm
Powered by Dreamwidth Studios