We BlogEditors of the new DK5 Manuals group are mild-mannered tech writers in the documentation Open Beta.
We are here to click buttons (Yeah!) and take screenshots and usernames
(so we can give credits in the manuals to people who helped).
DK5 Front Page Logo
DKos management (specifically staffers navajo, Meteor Blades, and elfling) has created a new group for this project, DK5 Manuals, where we can discuss writing our Reference and Tutorial Manuals, covering all of the changes in DK5, and indeed everything that will not change from DK4 as well. We invite contributions from any interested Kossacks with bug reports, feature requests, questions, or issues with the draft manuals, by many different methods. Since the Beta site is on a different server from the main dKos site, we have two DK5 Manuals groups,
one to publish DK4 Diaries like this one, and
one to publish DK5 Diaries, including a version of this one in a different layout.
Follow me below the jump, where I will explain how the DK5 Manuals project fits into the DK5 Open Beta and moves it forward, and how you can help. Because the draft manuals are having an Open Beta of their own.
The draft DK5 Click by Click Reference Manual is proceeding apace, with three of us writing regularly at Booktype: myself, Joy of Fishes, and greenbird; and contributions taken from many Diaries and Helpdesk discussions and wherever else we find it. Although she is not going to do a lot of the writing, elfling has joined as an Editor, checked out our work, and made a few additions and corrections to the draft. Thanks, elfling.
Founding
DKos management has decided to split this manuals project off from the FAQ & KB Team group, where it got started, and to provide high-level guidance to the new group. My thanks to navajo, Meteor Blades, and elfling, who have been hugely supportive of this project, and who are leading this new group. Then there is this, from kos.
Beta site update, and yes, YOU are the focus group
Discussing the changes over at the beta site, Mokurai answered a question about focus group testing of the site by saying:
This right here is the focus group. All of us.
The concept of the open beta couldn't have been better summarized! You are all the most effective focus group ever assembled, and have already had incredible influence shaping the new site.
This means you, that is, us. As many of us as we can get.
Mission
What I said: here to click buttons and take screenshots and usernames.
We are going into the DK5 Open Beta site to click every button and link, select every item on every menu, and try every setting, and see what they do for non-members, novices, and old hands at DK4. We will attempt to provoke every user-level error message in the DK5 software, and then ask the developers what we missed. We mean to find the unfindable, discover the undiscoverable, and whenever possible explain the inexplicable. We will write it all down in order with all the screenshots you could ask for, and then we will go over it again looking for errors and omissions, with help from some of you, we hope. And then they will change the UI, and we will rewrite the text and take new screenshots. And if the drafts don't have all the illustrations you could ask for to make things clearer, just ask, and we will add them.
The draft DK5 Click by Click Reference Manual is intended to end up
- Crystal clear
- Complete in every detail
- Excruciatingly correct
Yeah, TMI [Glossary entry, Too Much Information], tl;dr [Glossary entry, Too Long; Didn't Read]. We don't expect anybody in particular to read all of it, just those who are as OCD as we are about such things. ;<Þ And in my case, super-ADHD with hyperfocus.
However, having done that as thoroughly as we know how, we will then proceed to write a DK5 Tutorial Manual that will start at the beginning, lead you through the essentials, and show you how to find out more about any part of DK5 when you need to, with special attention to known problems of people starting out in DK5. While you are waiting for that, I can recommend elfling's Diary on writing DK5 Diaries, linked below.
Some have expressed concern at writing documentation for a system in development that is constantly changing. I was a professional tech writer in Silicon Valley and a volunteer writing manuals for a range of Free Software for many years. Fast-paced Agile Documentation developed naturally alongside fast-paced Agile Software Development. It turned out that documenting changes is less work than designing, developing, and testing them, so that it was almost never difficult to keep up. In some instances, we were able to put a team of experts together and crank out a software manual, from just a title and rough outline to print-on-demand publication, in one week.
We aim to be so helpful that no new DK5 users, whether coming in new or being thrust in from DK4, will feel like skipping any of the information. (Oh, sure, like anybody reads manuals. We can try, though.) Or if they do skip it, they will get pointed back to it regularly when they ask Newbie questions, by groups that support new dKos users, along with the FAQs and the Knowledge Base and the groups like Welcome New Users publishing Diary streams aimed at the needs of novices. Or maybe the design team will think about putting more of the necessary information about troublesome features right in the UI, and correcting some of the out-of-date and inconsistent messages that are there now.
It's a real challenge to ourselves. Again, we need your help, and this is where the story of the Open Manuals Beta really starts.
We know, or rather we will know by the end of the Open Beta, nearly all of what we are trying to explain. Well, nobody knows it all, but somebody knows each of the bits. Some of you should come around and tell us what we got wrong or left out, and if possible how to do it better.
So if you find that our explanations do not explain, or our illustrations do not illustrate, tell us so. If you have an idea of how to fix it, so much the better, but ask as soon as you are clear that you have a problem. That is the only way the writing team and indeed the entire community can help.
You should report actual problems with the DK5 software to the Helpdesk (links below). We are monitoring the discussions there regularly for both questions and answers, for promises to fix bugs, and for the occasional design change.
You will be invited to treat all DK5 Manuals Diaries as Open Threads where you can bring up anything related in any way to the Beta. Not just the technical stuff, but how to apply it to getting More and Better Democrats. Boy howdy, have you seen all the Chuck Schumer/Iran Diaries? Including Woodchuck Schumer at Animal Nuz? (Yes, I said, I Would Chuck Schumer.) Oh, I am looking forward to taking on some of these pols with the new tables.
Resources
The DK5 Manuals project draws on all of the experience of the community. Here are some notable examples.
Diaries
Diaries (or possibly stories, posts, or articles) concerning DK5 mostly bear the tag DK5 (151 Diaries as I am writing this) if they appear in DK4, or #DK5 (143 entries) if they appear on the Beta site. There is a #DK5 link among the trending tags at the top of the DK5 Home Page. I gave you the link to kos's excellent Front Page story above. Several other people and groups have been writing about DK5 regularly and in important ways.
From VP Products and Technology Jason Libsch's Blog feed:
Getting Beta All The Time
Beta Gets Better
Ok, What do You Really Think About Tip Jars?
From Systems Specialist elfling's Magical Mystery Tour:
Tell me what HTML tags you need that are missing, and how you will use them
DK5 Tutorial: Writing a diary
From the Cranky Users group stream, in addition to republishing several of the stories linked above:
UPDATED: Issues with DK5. Big Ones.
They let the whole bunch of us barbarians crash the gates... which they may now regret.
But this means it's vitally important that we take our concerns to the feedback section of the helpdesk, and explain what are problems and issues are -- nicely, please. It's fine that we're venting and sharing our exquisite pain here, but let's not heap it on hard-working tech and designer types who are invested in doing a good job.
The Diary quotes elfling:
Last time we did more of a staged beta process, inviting in 10 people at a time or so to come and help us. We had to do that, because the hardware wouldn't take the load of all of you at once, but it had the net effect of insulating most of you from the earliest, roughest iterations. This time, we had the hardware capacity, so we opted for a more open and transparent process, which means you're all starting from the roughest draft.
You see? It's that much worse this time because the process is so much better, which means that it will soon be much less worse much more quickly. I didn't know about the DK4 Beta as a new user, and Booktype didn't exist, or I would have started writing these manuals
then.
When I look at complaints from only a month ago, I am actually pleasantly surprised that we have gotten as far as we have. Big thanks to the Helpdesk, and to the design and devel teams.
Cranky Users Are Cranky
And a month before that.
Then there is me:
DK5 Click by Click Reference Manual: Advise and Complain
DK5 Click by Click Reference Manual Project
Where Are My Steenkin' Badges, Kos?
Everybody who participates in the Beta gets a badge! Some of us have requested a new badge, different from the DK4 Beta Tester badge.
Trusted User, Member, Beta Tester, Rescue Ranger, Donor
Helpdesk
The Helpdesk Discussions page has three topics concerning DK5. Please take the time to let them know about your problems. Even if your problem is already under discussion, vote for it and say what software you are using to access dKos. They need to know how widespread problems are, and have some way to tell if it is an issue with a particular browser or browsers, or in the DK5 system.
For example, the spambots are currently set to extra-cranky. That means that they occasionally ban a new user who has done literally nothing on the site since joining. Fortunately, they can request unbanning at the Helpdesk. Unfortunately, a lot of them don't know that, and go away disappointed or even mad.
Did you notice that they left the Donate button off DK5? Ceolmhor did, and let the Helpdesk know.
You've just received the last donation you're going to get from me...
...unless you put an obvious, easy-to-find "Donate" button on your new website.
straw herring on Aug 05, 2015 @ 02:28 PM:
Hi! Thanks for pointing it out. I've poked our designer about this oversight. I think we had a discussion about it previously, but meant to put it in once we polish the final design.
We will note the absence of the Donate button in the draft until we can document its presence.
FAQ and Knowledge Base (KB)
The FAQ & KB Team group plans to wait until DK5 stabilizes before updating the dKosopedia FAQs or the Knowledge Base pages at the Helpdesk. We mean to have as much detailed information as possible ready and waiting when they get started.
But the old DK3 (link at the bottom of many dKos pages) and DK4 (link added to DK3 FAQ) FAQs on dKosopedia are still useful as far as they go, and a lot of the Knowledge Base is still relevant and accurate, especially the advice that doesn't depend on site features.
Hunter's unofficial Troll Rating FAQs are still quite good, even though it became Hide Rating (HR) in DK4, and is now called Flag in DK5.
Troll rating from dKosopedia
An Exegesis for Troll Rating
The site's goal is still More and Better Democrats, and the Prime Directive is still DBAD (Don't Be A Dick). It's like the first of the Buddhist Pure Precepts.
Cease from evil
You really can't get anywhere with the rest until you have that one reasonably under control, in depth and in detail. Yup, that's going in the manuals.
Now, what's on your mind about the Beta site or the Beta manuals?