denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
I'm looking to update the Guide to DW for LJ Users since we have so many people coming over this week, and realized that I haven't been following LJ development over the past few years closely enough to update the things LJ has that we don't! So, if someone who's been holding dual siteizenship for the past two years can help me make a list of things LJ has implemented since we branched off from them that we haven't integrated yet, that would be awesome.

Off the top of my head:

* Statistics/My Guests
* Repost-this-post button
* Private notes about other accounts

What am I missing?
dubhain: (Default)
[personal profile] dubhain
(Because I'd like to make my debut post with something useful:)

As DW's style manual states that FAQs should have a readability of 8.0-9.0 on the SMOG Readability Scale, and because I really hate trying to calculate such things manually, I refer anyone interested to: The SMOG Calculator.

Also? O hai, everyone.

(Ducks, to avoid bricks and brickbats being thrown at him for the heinous use of lolspeak in a [site community profile] dw_docs post.)
silverflight8: Barcode with silverflight8 on top and userid underneath (_support)
[personal profile] silverflight8
*takes breath*

So, [personal profile] sofiaviolet and I have gone over the Journal Entries FAQ.

I've linked everything in this entry. I strongly suggest you not try to browse using that, because cuts don't work when you click on an entry. Instead, all the FAQs and the master post thingy are tagged dw support. Everything is public (or should be; if it isn't, send me a PM or a comment or something.) Everything should be in standardized form and linked to everything relevant (let me tell you I have never been so organized. Ever.)

In the monster post, FAQs crossed out but not linked meant I didn't think was missing anything. If you think there's something to add, please comment to that post. Missing/wrong/extraneous info in the FAQs should go to their respective FAQ entries.

Basically, I'd be really grateful if: )

Locking this to members-only in case this should be posted elsewhere, and to temporarily limit the audience.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
So, docs! I know it's been sadly neglected over the past few months. [personal profile] matgb will be stepping in to give things a hand over time, but he's suffering from Life Explosion right now and hasn't gotten a chance to really get up to speed.

What I'd like to do, in preparation for a big Docs Push in second quarter or so, is "adopt out" each of our FAQ categories: have people claim them to work on updating existing FAQs and identifying gaps in each FAQ category for FAQs that need to be written. The categories are:

FAQ cats )

Cat wranglers (cat herders?) would:

* Read over each FAQ in the category and revise them for style, prose flow, and accuracy.

* Add any new material needed, such as things DW has developed since the last revision.

* Identify any new FAQs needed and file bugs in Bugzilla for them to be written. (Or write them yourself!)

You would need to have strong writing skills and a good knowledge of how DW works. (You don't have to be a DW master, but you should be willing to explore and poke at things, and to read back over old code tours in [site community profile] dw_dev to see what's changed and what needs to be documented.) At first, you'll post your revised versions here to [site community profile] dw_docs; over time, once you get more established, we can give you the ability to edit the FAQs on the live site yourself. Be sure to read the Manual of Style!

If you want to adopt a FAQcat, comment here with the category you're interested in. If you and a friend want to work together on a single cat, that's fine -- just work it out amongst yourselves and let me know.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
New FAQs:

* What extra services can communities benefit from? in Your Account

* What is the difference between my journal style and the site skin? in Your Account

As always, I proofread carefully, which means there are at least four spelling errors lurking. If you spot a problem, holler.
[personal profile] rho
A quick note for those of you who don't read [site community profile] dw_styles: [personal profile] foxfirefey is planning the documentation of all things S2 over there and would appreciate any help you could give!
[personal profile] rho
Have any suggestions for things that you think should be documented but aren't, things about the current documentation that you think need improving, or any "hey, wouldn't it be neat if..." ideas that pertain to docs? Comment here with them, and I'll either fix them, put them in zilla, or explain why I don't want to do them.
[personal profile] rho
A few things to bear in mind for anyone wanting to write documentation for us.

1. We have a manual of style which will tell you such useful things as how you should use "email" instead of "e-mail" and how you should never use comma splices.

2. The general aim of our FAQs is to convey information as clearly and concisely as possible. This means that it's often better not to include all information possible that pertains to a subject, since that just leads to information overload. Ideally, no FAQ should be longer than about 3 or 4 paragraphs long unless there's a good reason. We want people to be able to find the information they're looking for without feeling as if they've got to read a thesis first.

3. Always aim for accessibility in everything you write, and remember that different people will be accessing the page in different ways. There are different site schemes, different styles, text only browsers, screenreaders, and so on and so forth. Saying "click the icon that looks like a bell on the left hand side of the screen" is utterly useless to people who aren't using a screen and can't see images. I'll go into this in more detail at a future point, but for now, it's something to be aware of.

4. There are various FAQ variables that you can use in FAQs to do things like show the username of whoever's viewing the page.

5. Give it a go! If you see anything in zilla that takes your fancy, assign it to yourself and give it a go. I'm happy to work with people to polish up first drafts to be more in keeping with our standards.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
Bugzilla looks complex and complicated, but it's actually quite easy once you master a few basic principles! Here's how to find, enter, and work on docs-related bugs.

Finding docs bugs )

Entering docs bugs )

Working on docs bugs )

I think that should cover the most common use cases! Am I forgetting anything?
[personal profile] rho
I'm the first to admit that docs has it's problems and isn't running anywhere near as smoothly as it could or should be. Part of this is down to my being busy with Real Life for the past several months, but part of it is also that the tools that we have for managing our FAQs pretty much stinks.

The system was designed on LiveJournal many years ago and it hasn't scaled well at all. One of the biggest problems, from an administrative perspective, is that there's no system in place for review and approval. Obviously, we want for anyone who is interested to be able to help with writing FAQs. Equally obviously, we can't just give anyone who shows interest the ability to edit the FAQs at will, because we need a system of quality control.

Let's say that you'd seen an omission or error in a FAQ, and rewrote it accordingly. What would then need to happen is for you to send what you've written to me, somehow, then for me to check that the change you'd made was good and then go into the FAQ admin interface and make the change. Given that the admin interface is also dated, this is something of a nightmare.

We have detailed plans for a completely new FAQ system that will solve this problem for us, but it's going to be a fairly major development project, and all our developers have other projects that are a higher priority at the moment. In the meantime, we have to make do with what we've got as best as we can.

We've tried a few different ways of organising things in the past, and truth be told, none of them have worked. [staff profile] denise and I have been plotting, though, and we're ready to bring out another approach, and we're hopeful that this time it will stick. We think this is going to be the best compromise we can make between a low barrier for entry for people wanting to get involved while simultaneously not being an administrative nightmare.

What we're going to do is start using zilla, the same system that our developers use for tracking bugs. We were slightly reticent about this, because it isn't the most user-friendly interface in the world ever, but really, once you get used to it, it's quite simple and intuitive. More importantly, it's also a mature project management tool which can make things a lot easier from the administrative end.

[staff profile] denise is going to be along shortly with a bit of a guide to zilla, and I'm going to keep the full explanations of how this is going to work until after she's posted that, but essentially, what will happen is that zilla will contain an up to date list of issues with the FAQ that need working on, anyone can assign any of these items to themselves, and once they've written the new FAQ or new version of an existing FAQ, they can upload it to zilla as an attachment and mark it as needing admin attention, at which point I or [staff profile] denise or someone else can come along and add it to the FAQ on site.

At the moment, there aren't all that many documentation items in zilla. After we decided we were going to work things this way, I just put a few of the larger, higher priority items in so we didn't have an empty list. As time goes on, I'll be putting more things in there and I'll also be soliciting suggestions here for things that need adding or changing.

We're still a little unsure of a few of the details of how this is going to work, and we'll probably change things about a little as we see things in action, but I'm confident that this is going to work so please do bear with us.

Questions are not only welcomed but also encouraged.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
Anybody want to take on the task of going through all of the FAQs and removing the .bml from the ends of links? Someone pointed out that doesn't work anymore since we TT-ized those; I fixed the links in the FAQ she pointed out, but it made me realize that we probably have tons of .bml links in the FAQs.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
I realized it's been a while since there's been a "suggest improvements to the FAQ and site copy" entry. This is that entry.
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
We've just passed 6 months of open beta, and we've been developing like madmen and madwomen, so there are a bunch of cases where our FAQs are out of date or there are new features that aren't documented anywhere but in code tours/news posts.

This/next week, I am making it my project to:

a). go through every single FAQ on the site to identify things that need to be updated (wrong limits, feature enhancements, etc)
b). write new FAQs for all completely-new features that aren't yet documented.

This is not so much to ask for help -- it's the kind of full-on scrub that I think is best done by a single person to make sure things don't fall through the cracks -- but it is a request for pointers! What things have you noticed that aren't documented/are underdocumented? (For instance, sticky entries aren't really well-documented at all, etc.) I'll be making my own list, and going through past code tours, but I never remember everything our site can do and could use a hand :)

Caps edit

Oct. 29th, 2009 11:42 pm
denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
[staff profile] denise
We've just made two changes to the caps file (who can do what):

* All users (not just paid users) can now post by email.

* Userpic limits upped: free users get 15, paid users 100, premium paid 250

Requesting documentation thereof!
[personal profile] rho
It took a little longer than I'd hoped, since my life is being busy right now, but this is the first draft of the specifications for the new FAQ system that we're going to write. At this point, please comment liberally. Consider this a call for feedback as much as anything else. How does the proposed system sound to you? Is there anything that I'm missing? Is there anything that sounds particularly awesome or desirable? Are there any bits that aren't clear?

Specifications, draft 1 )

PS Sorry for the formatting. I wrote this up as a text document, so some formatting is lost here.
[personal profile] rho
Short summary version of this post: things have been sucking, I know, I'm sorry, we're trying to make things better, watch this space for more.

Much as I hate to admit it, docs has been a bit of a mess since we went into Open Beta. We've been behind on getting new information up, there have been a lot of people who have been wanting to help but haven't been able to, and things generally haven't been going as smoothly as they should.

As head of all things docs, I take full responsibility for this, and will accept any rotten fruit you feel like throwing at me. I deserve it. However, as a personal favour, I'd like to request that you go easy on the rotten tomatoes. I hate tomatoes.

So what's been going on, and where are we going from here?

First thing I need to report is that [profile] ivorygate has stepped down as co-admin of docs due to an excess of Real Life, so I'm flying solo again. I'd just like to stress again that any problems we're having are my fault and not hers, and thank her for all the work she's done.

On a happier note, I've just got back from a 6 week holiday, and now that I'm home and recovered from the killer jetlag of transatlantic travel, I'm finding that a lot of the burnout I'd been feeling before has gone away, and I'm viewing Dreamwidth with a brand new energy and enthusiasm again. Hurrah. My task is going to be to dig us out of the hole I've landed us in and get documentation working again.

[staff profile] mark stole my thunder a little by mentioning this in the main update over in [site community profile] dw_news yesterday, but I'd like to go into a bit more detail here. One of the big problems that we have with documentation is that the FAQ system that we're using which we inherited from LiveJournal is old, and boy does it show. It's had a few minor updates over the years, but by and large it's still exactly the same system that [ profile] brad first put in place about a decade ago.

Generally, when using this system, it feels a whole lot more as if we're fighting against it than working with it, and that sucks. This is one of the reasons why there are plenty of people wanting to help out who can't. The system just isn't designed to work well with big projects requiring a lot of people. We tried various ways to try to get more people involved, but none of them really worked. I'm proud of what we accomplished for open beta, but the administrative work for that just about killed me (because of the system; not because of the awesome people) and was what led to burnout I mentioned before.

The good thing now is that with [staff profile] mark working for Dreamwidth full time, we're going to have the opportunity to rewrite the whole documentation system from scratch into a form that actually suits our needs and does what we want it to. One of the things that I'm trying to focus on in designing the new system is to make sure that it's as easy as possible for people to get involved. I know there's a mass of untapped potential out there from people who want to help but haven't been able to, and I really want to be able to harness that potential to make something awesome.

I'm still working on the specifications for now (for those who aren't familiar with the workflow involved here, I'll be writing the specifications for exactly what the new system should do and I'll then pass them onto [staff profile] mark who will write the code to actually build the system) so I don't have anything concrete to share at this point. Hopefully I'll have a first draft specifications done in a day or two, at which point I'll post them here for discussion and brain-storming.
ivorygates: (DW LOVE NOT WAR)
[personal profile] ivorygates
This is the September thread for suggesting new FAQs, suggesting changes to existing FAQs, posting errors in existing FAQs, and for changes to/additions to/errors in site copy which is not FAQs.
ivorygates: (Default)
[personal profile] ivorygates
This is the August thread for suggesting new FAQs, suggesting changes to existing FAQs, posting errors in existing FAQs, and for changes to/additions to/errors in site copy which is not FAQs.
ivorygates: (dreamwidth social content with dimension)
[personal profile] ivorygates -- the FAQ on the Crossposter has been updated to remove a reference to the cut tags bug. The Known Issue about mood icons has been added -- "The Feed I'm Following Isn't Updating. Why?" has been reformatted for easier reading.
ivorygates: (Default)
[personal profile] ivorygates
This is the July thread for suggesting new FAQs, suggesting changes to existing FAQs, posting errors in existing FAQs, and for changes to/additions to/errors in site copy which is not FAQs.


dw_docs: Dreamwidth d logo, with text "dw_docs" (Default)
Dreamwidth Documentation

September 2016

25262728 2930 


RSS Atom

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Sep. 19th, 2017 01:33 pm
Powered by Dreamwidth Studios