Plain Black, makers of WebGUI - Re: Buying documentation from plainblack

bernd

Date: 9/6/2008 2:46 am · Subject: Buying documentation from plainblack · Rating: 0

Yesterday, a stupid idea came to my mind: Something that has been bothering me about WebGUI for a while is that it does not come with a decent online help. I believe that this really hampers its spread in the online world. My co-administrators, for example, often have problems with adding new content. But whenever I offer them my hardcopy of the content manager's guide they refuse to take it. They do not want to spend so much time on reading. In addition, I only of one copy.

I know that it is a lot of work to write documentation. I have authored many documents myself. And I understand that it costs a lot of money. But what if the community would cover these costs, i.e. if we would alltogether buy the copyright of existing guides from plainblack and put their content into a public wiki. There, they would not only be available to everyone but could also be maintained by the community.

Of course, this does not only depend on the willingness of the community to pay for documentation but also on plainblack. But maybe there is some interest. In addition, we could start with one guide after the other.

Personally, I would be willing to throw in $200 (private user). Who else is interested?

Bernd

--
Administrator of a non-profit community portal for free-climbers around Magdeburg/Germany. Check out http://www.klettern-md.de.

--- (Edited on 06.09.2008 09:46 [GMT+0200] by bernd) ---

Back to Top

Rate [ | ]

koen

Date: 9/6/2008 7:59 am · Subject: Re: Buying documentation from plainblack · Rating: 0

How would you suggest to keep that public wiki at high quality?

At least with the books PlainBlack makes sure that everything that is in there is correct at the time of publishing.

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization

--- (Edited on 6-September-2008 14:59 [GMT+0200] by koen) ---

Back to Top

Rate [ | ]

bernd

Date: 9/6/2008 8:50 am · Subject: Re: Buying documentation from plainblack · Rating: 0

Am Samstag, den 06.09.2008, 14:59 +0200 schrieb koen@procolix.com:
> How would you suggest to keep that public wiki at high quality?

That is indeed the big issue. But other open source projects have
managed that as well. I am quite confident that this can work.
Maintaining documentation is much easier than writing it from scratch.
And with respect to new features one could simply require documentation
prior to submission to the core. That is true for the code itself
already.

> At least with the books PlainBlack makes sure that everything that is
> in there is correct at the time of publishing.

But for updates you have to buy the whole book again and more
importantly the update process is slow. In addition, hardcopies are less
convenient to use. There is no search function, for example, and users
cannot add comments.

If you (or everyone else) are not convinced we could start an experiment
with a single guide book first. If that does not work we can still
return to the old system.

--- (Edited on 9/6/2008 8:50 am [GMT-0500] by bernd) ---

Back to Top

Rate [ | ]

koen

Date: 9/6/2008 2:09 pm · Subject: Re: Buying documentation from plainblack · Rating: 0

There is allready a wiki on webgui.org I don't see that working really well, so let's start at making that wiki a good source of documentation.

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization

--- (Edited on 6-September-2008 21:09 [GMT+0200] by koen) ---

Back to Top

Rate [ | ]

bernd

Date: 9/7/2008 7:54 am · Subject: Re: Buying documentation from plainblack · Rating: 0

There is allready a wiki on webgui.org I don't see that working really well, so let's start at making that wiki a good source of documentation.

You are right. The current wiki is not working that well. The problem is that since we are all responsible in the end no one is. What we need in my oppinion is someone responsible for structuring the content, i.e. for maintaining the TOC, harmonizing page names, merging articles that belong together and announcing pages that need to be updated. So maybe we could anounce a wiki manager every 2 or 3 months and take turns in filling that position. And if the honor of being announced was not sufficient :-) the wiki manager could further be rewarded with some karma in the end.

Bernd

--
Administrator of a non-profit community portal for free-climbers around Magdeburg/Germany. Check out http://www.klettern-md.de.

--- (Edited on 07.09.2008 14:54 [GMT+0200] by bernd) ---

Back to Top

Rate [ | ]

knowmad

Date: 9/7/2008 7:28 pm · Subject: Re: Buying documentation from plainblack · Rating: 0

Bernd,

I agree that better online documentation is essential to the success of WebGUI; and I think that PlainBlack is listening. At the WUC, JT announced that they are making the WebGUI Primer free of charge to download as a PDF from the PlainBlack Store. In addition, you can still buy printed copies.

Your idea is interesting, but I have no interest in trying to buy the rights of their documentation. I'd be more interested in seeing a community project to improve the documentation. Personally, I thought removing the online help from WebGUI was a big loss (I'm talking about the help icon that lived at the top left of the asset edit pages, not the remaining Help system which is far more technical than a typical user would find useful).

Although the online help system was limited, it's size was apparently causing a severe performance/resources hit to the servers. Perhaps the community can find a way to link back to the wiki for context-aware help and links to additional ways to find help (forums, IRC, etc). Ideally, there should be "official" wiki entries that allow comments but not edits, except by authorized users.

William

----
Knowmad Technologies
http://www.knowmad.com

--- (Edited on 9/7/2008 8:28 pm [GMT-0400] by knowmad) ---

Back to Top

Rate [ | ]

bernd

Date: 9/8/2008 5:35 am · Subject: Re: Buying documentation from plainblack · Rating: 0

Hey William,

I agree with most what you said. Let me summarize my thoughts:

1. WebGUI shall be extended by an online help system. The help system
shall provide rather a brief reference than an extended guide. Advanced
books shall still be supplied through plainblack, freelancers or other
service providers.

2. Ideally, the reference manual would be placed in a separate wiki with
read access to everyone and write access to documentation maintainers
only. Everyone should be allowed to edit pages based on an approval
workflow. Adding comments shall be allowed to everyone.

3. Documentation managers shall be assigned by the community on a
rotation principle. Documentation managers are responsible for defining
the outline of the manual and keeping the TOC up to date. They further
indicate sections that need to be updated and are responsible for
removing obsolete information.

4. The job of being a documentation maintainer should be awarded with
some karma at the end of each period. Contributing community members
shall receive karma for writing and editing documentation similar to the
discussion board.

5. All assets within WebGUI shall link to respective sections in the
wiki. That way documentation is always up to date and does not put a
burden on the server. Additional links to the reference manual shall be
placed wherever this is appropriate.

6. The reference manual shall be written and maitained by the community.
Possibly, the initial content can be bought from plainblack.

Is that your idea as well?

Bernd

--- (Edited on 9/8/2008 5:35 am [GMT-0500] by bernd) ---

Back to Top

Rate [ | ]

koen

Date: 9/8/2008 4:42 pm · Subject: Re: Buying documentation from plainblack · Rating: 0

Before you read my comments:

I think it is really great you are spending your time on trying to help WebGUI and it's community go above and beyond.

ProcoliX has funded the Dutch translation for some 6 years now so I think I can speak from experience when I say helping the community go forward in a constructive manner will cost you dearly if you want to do it right. That is still not a reason to not do it.

The rules for the game are better set during the game, so at least you get to play with each other, then before the game since that way you'll maybe never start playing it.

My general advice is: start the process and make up the rules while in the process. and you'll get done a lot more.

1. WebGUI shall be extended by an online help system. The help system shall provide rather a brief reference than an extended guide. Advanced books shall still be supplied through plainblack, freelancers or other service providers.

I think that if this is a suggestion of yours you should put it in an RFE. If you want PlainBlack to buy into it you will most definately have to phrase that out a bit more humbly.

2. Ideally, the reference manual would be placed in a separate wiki with read access to everyone and write access to documentation maintainers only. Everyone should be allowed to edit pages based on an approval workflow. Adding comments shall be allowed to everyone.

I think the best way to achieve this is start writing a lot of documentation in the wiki. So long as there is no-one really writing documentation I think no restraints will be put on the wiki by PlainBlack. And I think they would be right in not doing that too.

3. Documentation managers shall be assigned by the community on arotation principle. Documentation managers are responsible for defining the outline of the manual and keeping the TOC up to date. They further indicate sections that need to be updated and are responsible for removing obsolete information.

Again, if there is more then a hand full of people writing the actual documentation and keeping the TOC up to date no restraints will be put on the wiki.

4. The job of being a documentation maintainer should be awarded with some karma at the end of each period. Contributing community members shall receive karma for writing and editing documentation similar to the discussion board.

I would say: all effort in helping the community forward should be rewarded by karma. Including editing the wiki and writing documentation. If you where to write up a more or less complete guide on implementing karma in a website documenting all the options in all possible ways I'd be willing to give you 500 karma for that.

5. All assets within WebGUI shall link to respective sections in the wiki. That way documentation is always up to date and does not put a burden on the server. Additional links to the reference manual shall be placed wherever this is appropriate.

Once enough parts of the WebGUI system have been documented in the wiki this is possible, before that I think it would even be wrong to do this.

6. The reference manual shall be written and maitained by the community.

Nice Idea, again, start writing it, the community will follow.

Possibly, the initial content can be bought from plainblack.

I think buying the documentation from PlainBlack is nearly impossible. It is probably cheaper to hire a company to document everyting again.

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization

--- (Edited on 8-September-2008 23:42 [GMT+0200] by koen) ---

Back to Top

Rate [ | ]

bernd

Date: 9/9/2008 2:47 am · Subject: Re: Buying documentation from plainblack · Rating: 0

The rules for the game are better set during the game, so at least you get to play with each other, then before the game since that way you'll maybe never start playing it.

I mostly agree. Still it is good to have a concept in the beginning. Ideally, this makes sure we are talking about the same thing.

My general advice is: start the process and make up the rules while in the process. and you'll get done a lot more.

Koen, are you saying I should get to work? You are probably right ;-) However, I want to point out that this one is too big to be handled just by me alone. I have created a new wiki article for defining the outline of the reference manual. Currently, it is rather a wish list. But maybe, you want to have a look and add your points.

1. WebGUI shall be extended by an online help system. The help system shall provide rather a brief reference than an extended guide. Advanced books shall still be supplied through plainblack, freelancers or other service providers.

I think that if this is a suggestion of yours you should put it in an RFE. If you want PlainBlack to buy into it you will most definately have to phrase that out a bit more humbly.

I want to apologize if I did not hit the right tone. This is only due to my limited language skill. Indeed, I am planning to sumbit various RFEs. But first I want to discuss this a bit more in order to find out what is the consensus.

2. Ideally, the reference manual would be placed in a separate wiki with read access to everyone and write access to documentation maintainers only. Everyone should be allowed to edit pages based on an approval workflow. Adding comments shall be allowed to everyone.

I think the best way to achieve this is start writing a lot of documentation in the wiki. So long as there is no-one really writing documentation I think no restraints will be put on the wiki by PlainBlack. And I think they would be right in not doing that too.

Absolutely correct. We can start in the common wiki and transfer articles to a separate wiki later on. Restrictions should be put in place only if necessary.

4. The job of being a documentation maintainer should be awarded with some karma at the end of each period. Contributing community members shall receive karma for writing and editing documentation similar to the discussion board.

I would say: all effort in helping the community forward should be rewarded by karma. Including editing the wiki and writing documentation. If you where to write up a more or less complete guide on implementing karma in a website documenting all the options in all possible ways I'd be willing to give you 500 karma for that.

Is the karma function already implemented for the wiki? I mean technically speaking..

Possibly, the initial content can be bought from plainblack.

I think buying the documentation from PlainBlack is nearly impossible. It is probably cheaper to hire a company to document everyting again.

What makes you think so? I could imagine it is in their interest as well. Unfortunately, none of them has commented so far.

--
Administrator of a non-profit community portal for free-climbers around Magdeburg/Germany. Check out http://www.klettern-md.de.

--- (Edited on 09.09.2008 09:47 [GMT+0200] by bernd) ---

Back to Top

Rate [ | ]

LoopSetShop

Date: 9/9/2008 6:08 am · Subject: Re: Buying documentation from plainblack · Rating: 1

Koen, are you saying I should get to work? You are probably right ;-) However, I want to point out that this one is too big to be handled just by me alone. I have created a new wiki article for defining the outline of the reference manual. Currently, it is rather a wish list. But maybe, you want to have a look and add your points.

Great idea! The WebGUI Wiki really needs some more structure.

I've added some points and gave an update to Macros, List of Available. It now has links to all other wiki pages about the individual macros. At least all that I could find.

--- (Edited on 9-September-2008 13:08 [GMT+0200] by LoopSetShop) ---

Back to Top

Rate [ | ]

Buying documentation from plainblack

Recent Discussions Color Key