****LONG POST AHEAD***
I'm intrigued by this idea. Currently, the documentation is directly competing with new features for resources. If we could improve the documentation without significantly slowing down development, it would be a huge win.
I assumed that very thing... with your limited manpower resources, it seemed a logical path to expand the task to outsourcing.
I'm just not sure how best to tackle that, so what are you envisioning?
See Below for detailed response.
Also, I seriously question whether the documentation actually gets read by most users.
If so, would video tutorials be better? Or something else? What do you guys recommend that would be the most use to the largest number of users?
I for one use it frequently... as Chemlak described... Did I read it intently from cover to cover when I got RW... admittedly.. no, but I seldom do any software documentation.
As to best course / best practice see below....
Regarding documentation:
...........................There should be something akin to a quick start guide: here are some basic concepts (topics, snippets, containers, relationships, etc), here's a basic idea on how to use the storyboard, here's what the almanacs are for. Pretty broad stuff, with just enough detail to let a user get things done ("click the + on the relationships section, select a relationship type, add any notes, click ok.").
And then there should be the full-blown "here's how to do everything" document, which provides the same information (redundancy is your friend), but also gives the whole nitty-gritty on every possible trick (when to use a simple relationship or an arbitrary relationship, why identifiers matter, etc).
Agreed... this is similar to other software (in mass of what is to be learned) such as MS Office Products or in the Day WordPerfect... I have to
CTRL A to get??? what??
CTRL Shft A to get WHAT??Most people are overwhelmed and intimidated when it comes to learning robust or complex things, especially new software. They utilize those massive books as door stops and paper weights.
Even to this day I still utilize AutoCAD the "old way" through key stroke short cuts I learned all the way back in ACad 2.1. Point is will most use the exhaustive full blown documentation... probably not. Just like word or excel there are HUNDREDS of features that are almost never used. Macros, VBA, just to name a few.
Chemlak's approach is just as I see it....
- A Get you Started book that fits the need of 80%....
- An Exhaustive Reference for those that want to know everything.
- A Tricks and Tips Compendium for things that could be done multiple ways depending on user preference. With the Risks vs Reward of the approach?
I've already admitted that I'm pretty terrible at reading documentation, but that's not entirely true: I skim documentation to see what it covers, and then only refer to it when I reach a "how do I do this..." moment. As long as the solution is actually in the documentation.
DITTO that is my defacto approach to 99% of the software I utilize. BUT I rely a great deal on my background experience in dealing with a multitude of different software certainly bolsters this.
As for getting users involved in helping with documentation, I think it's a fantastic idea, but complicated by the risk inherent in "you get what you pay for". I'd suggest asking for volunteers, cherry-picking the applicants (don't make it a free-for-all, treat it more like a Beta team application), and asking them to write a sample piece, using the existing guides as a style template, with a deadline. I'd be very surprised if it was wasted effort.
Chemlak has a similar vision to what I was thinking.
Obviously if this were driven thru the community, it would be volunteer.
However, I disagree with the "write a sample piece and deadlines".
One, it isn't a job application (though it "could be" more on that in a bit) and disagree with the deadline... LWD has already proven what a slippery slope that can be... don't get me wrong.. I am a stickler for DEADLINES.. but as it is also volunteer and we all have "day jobs" that would be a constraint as well. Now I am not saying the reverse either, that would leave things never getting done.... But remember, there WILL BE addendums and additions will always occur as this software evolves. It's no different than writing procedures. As the environment changes, so will the framework that defines the course of action. A nomenclature would be prudent to add to the book defining what was updated and when.
And I agree with the "you get what you pay for" but only to a point. Remember, you aren't "paying".... unless of course we define some other form of currency? Differing moniker for log on, accolades in news letter, credits in market place, donno, there are possibilities here.
As to the Beta Team approach, I "kinda agree" with this detailing.
I would propose the following.... On another forum I am a contributing writer.
We, as the community, define the topic, then any can write a submittal, posting it in the forum. the community makes comment or if applicable "canon" corrections, and then the moderator and the editor's gleen the topic material for final publication.
With this approach, the community does the rough draft read / correcting, and then the editor takes the "finalized" version to print.
So in a sense, it would go something like this:
- Instead of the community picking the topic, the writer would (based on what he/she feels is within their skill set to write on)
- the "Beta Team" would be the community. Reviewing the writing of the piece for errors, oversights, or omissions.
- Writer collects and corrects based on feedback
- When the writer has collected and corrected all the feed back, submits to Editor (Rob or designee) for approval and addition to edition (Quick Start, Full Ref, or Tricks Tips)
- Editor Rejects or Approves Submission
- If Editor rejects, either sends back to writer (private IM here?) or posts back to thread with BRIEF comments.. "what aboutblah?" or missing / incorrect info.
- If editor Approves, IM to Writer Approving submission, or on thread.
- Editor updates published "book" & nomenclature for revision change
- Rinse Repeat
This methodology allows simultaneous workings on multiple fronts, simultaneously.
The real trick here is multi fold.
- The writer must define what part he/she is working on So there is no overlap of work effort from the community side.
- The community must be cognizant of the thread and know who/what is being worked.
- There should be a forum topic dedicated to reference materials (preferably separated by each type Quick Start, Full Ref, etc) to capsulize each effort.
- There should be a means to mark the thread complete when the writer has submitted and the editor approves and publishes (Colen maybe here??)
- Lastly & most importantly, the community would have to refrain from posting questions and wishes within these threads. They would not be for I wish it did this.. or how do I do that... that is what the other threads are for (again a forum moderator thing)
At first it may not limit your (Rob or designee) role but would shift it from writer to editor. Once the learning curve for both on expectations are achieved, it should / would lessen the allotted time the "editor" would spend reviewing and gain more "free time" (big HAHA here) for other items like development, where their skill sets are more needed... Most "dedicated" RW users have proficiency in word processing over the programing language RW is written in and we aren't defining a developers manual (yet? haha) so the techno lingo isn't required.. So I foresee a win win......
Pie in the Sky part-
This application could also apply to video tutorials as well
A list of TBD for each publication could serve as the "ToDo" list... (for now we can simply look at what is published)
Additionally, as the TBD of the collective books start to fill in, the work load will slow to only addendums and updates.
Just my 2cp
