Dreamwidth Documentation

faqedit privs

Thu, 19 Apr 2012 03:50:29 GMT

It's been a while since we've doen any updating to the list of who has faqedit privs -- not since the days of closed beta, in fact! -- and I've been horribly remiss on staying on top of that. So, two things:

* I've removed privs from anyone who still had faqedit privs from the days of closed beta. This is not to say that you all aren't more than welcome to return to FAQ work! I just wanted to start from a "clean slate", so to speak.

* In the future, anybody who has done more than 5 docs bugs can talk to me about getting faqedit privs. (This mainly consists of taking FAQ changes that are uploaded to Bugzilla, copyediting/style-editing them, and making the changes on the site itself.)

You don't need faqedit privs to do docs changes -- just claim the bug in Bugzilla and upload an attachment with your changed version -- or to propose changes to a FAQ (for that, open a new bug in Bugzilla with a summary of the changes you think should be made).

Thank you to everyone who's done docs work thus far!

comments

revision to manual of style

Sat, 25 Feb 2012 23:08:16 GMT

I've revised the Capitalization section of the Manual of Style to reflect that I've changed my mind about capitalizing DW-specific concepts like "Paid Account", "Access", "Access Filters", etc.

It now reads:

== CAPITALIZATION ==

Capitalize the title of the page when you're referring directly to another site page, such as the Manage Journal page. For other uses, use your discretion. If it would be easy to mistake a DW-specific concept for another common word, or if you're mixing usage of the common word (not to refer to the DW concept) and the DW concept, capitalize the uses of the DW concept. Otherwise, default to lowercase unless the site text (not the FAQs) consistently capitalizes the concept. (A little inconsistency is okay; don't sweat it too much.)

When you're referring to something that's in common use on the Internet or that a beginning user would likely be familiar with, such as tags, bookmarks, etc., use lowercase.

The name of the site is ''Dreamwidth'', with an initial capital and no internal capitals.

comments

filing bugs for needed FAQ updates

Thu, 02 Feb 2012 19:57:34 GMT

The perpetual bane of any product is making sure the documentation is up to date. We've been falling down on documentation for a while, and there are lots of reasons for that but I'd once again like to start trying to change it. Now that it's a new year, it's time to once again start in on a concerted effort to figure out what's missing from the FAQs (and then, of course, work to fix that, but the first step is identifying the scope of the problem!)

I have a few people working off the code tours to identify what we've added that needs to be documented, but consider this an open invitation to join them. If there's something you identify as missing from the FAQ, please open a bug for it (or if you don't want to navigate Bugzilla, you can just leave a comment here and someone will move it into Bugzilla for you).

See Bugzilla: How to enter, find and work on docs bugs for reference, and the list of open docs bugs to see what's already been reported.

comments

Sun, 10 Apr 2011 07:42:37 GMT

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?

comments

SMOG Calculator

Sat, 02 Apr 2011 04:54:05 GMT

(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 dw_docs post.)

comments

Request for - ah - beta readers, suggestions, and paid users who like testing things

Thu, 03 Mar 2011 07:33:42 GMT

*takes breath*

So, 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.~~

comments

Adopt a FAQcat

Wed, 26 Jan 2011 09:37:43 GMT

So, docs! I know it's been sadly neglected over the past few months. 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 dw_dev to see what's changed and what needs to be documented.) At first, you'll post your revised versions here to 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.

comments

Fri, 10 Sep 2010 15:09:51 GMT

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.

comments

Styles docs

Mon, 14 Jun 2010 03:49:52 GMT

A quick note for those of you who don't read dw_styles: foxfirefey is planning the documentation of all things S2 over there and would appreciate any help you could give!

comments

Docs suggestions post

Thu, 10 Jun 2010 05:18:35 GMT

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.

comments

So you want to write docs?

Thu, 10 Jun 2010 05:14:32 GMT

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.

comments

Bugzilla: How to enter, find and work on docs bugs

Wed, 09 Jun 2010 04:40:58 GMT

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?

comments

A new direction for docs

Wed, 09 Jun 2010 04:08:00 GMT

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

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

comments

Sat, 24 Apr 2010 21:03:47 GMT

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 http://www.dreamwidth.org/nav.bml?cat=create 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.

comments

FAQ/site copy suggestions

Tue, 16 Mar 2010 12:16:42 GMT

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.

comments

December FAQ Scrub

Tue, 08 Dec 2009 19:54:48 GMT

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

comments

Caps edit

Fri, 30 Oct 2009 03:44:52 GMT

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!

comments

Draft for specs of new FAQ system

Sun, 18 Oct 2009 05:32:57 GMT

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.

comments

The state of docs

Tue, 06 Oct 2009 17:03:44 GMT

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

mark stole my thunder a little by mentioning this in the main update over in 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 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 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 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.

comments

September Dreamwidth Documentation Suggestions Thread

Sat, 05 Sep 2009 08:36:45 GMT

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.

comments

August Dreamwidth Documentation Suggestions Thread

Wed, 05 Aug 2009 02:59:30 GMT

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.

comments

REVISIONS AND UPDATES TO FAQS: 16 JULY 2009

Fri, 17 Jul 2009 02:54:38 GMT

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=130 -- 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

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=108 -- "The Feed I'm Following Isn't Updating. Why?" has been reformatted for easier reading.

comments

July Dreamwidth Documentation Suggestions Thread

Thu, 16 Jul 2009 10:25:40 GMT

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.

comments

FAQ UPDATES

Tue, 14 Jul 2009 04:42:59 GMT

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=173 Revised. Information on how the latest code-push affects Transmogrified; fixes.

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=152 Revised. Information on the new BETA VERSION Suggestions Generator. Which doesn't, um, generate suggestions, but allows you to make them...

comments

Updates

Sat, 11 Jul 2009 05:54:06 GMT

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=175 "Can I Download My Dreamwidth Journal?" is a how-to on using the "Export Journal" Tool.

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=149 "Site pages do not display properly in older browsers, including Internet Explorer 6" discusses workarounds for site-surfing for those using older browsers.

http://www.dreamwidth.org/support/faqbrowse.bml?faqid=152 "Where can I leave suggestions for site improvements?" covers where you can make site suggestions.

comments