Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

All other Modules /

Discuss all other Modules here.

Moderators: martimiz, Sean, biapar, Willr, Ingo, swaiba, simon_w

Extending the user help


Reply


17 Posts   3425 Views

Avatar
walec51

Community Member, 16 Posts

9 January 2009 at 12:23am

Ok. SilverStripe is still an option.

But I don't understand why you want to have the developers documentation in a wiki engine and the user help in a cms engine. Both of them are not suitable for "quick fix'es" and both of them would require some approval mechanism.

As for keeping the editor group small. Ok, but keep in mind that this group will change frequently as people will rapidly just come and go to correct something wrong in the manual or when they what to add something. No one wants to develop a user manual all the time. So registering to the editors group would have to be easy and opened.

Avatar
Ingo

Forum Moderator, 801 Posts

9 January 2009 at 8:28am

> But I don't understand why you want to have the developers documentation in a wiki engine and the user help in a cms engine.
I'd argue that dev documentation changes far more frequently than the UI-design which has to be documented through userhelp. You can also expose devs to a bit more "fluidity" than end-users, hence the wiki approach. Thats not to say that we can't change dev documentation to be cms powered, but that would require some architectural changes (separating module-documentation and tutorial-contributions from core API documentation).

> As for keeping the editor group small. Ok, but keep in mind that this group will change frequently as people will rapidly just come and go to correct something wrong in the manual or when they what to add something. No one wants to develop a user manual all the time. So registering to the editors group would have to be easy and opened.
Ideally there's at least one "owner" of userhelp which keeps an eye on the changes, and a smallish group of frequent contributors. This group can pick up corrections/suggestions from the user comments. Typical too many cooks in the kitchen problem I guess. If you leave userhelp edits open to everybody, you get a dozen different writing styles, duplicate content, unreviewed incorrect information, etc.

Avatar
walec51

Community Member, 16 Posts

9 January 2009 at 12:08pm

> I'd argue that dev documentation changes far more frequently than the UI-design which has to be documented through userhelp. You can also expose devs to a bit more "fluidity" than end-users, hence the wiki approach.

Ok, I partially agree with this.

> Thats not to say that we can't change dev documentation to be cms powered, but that would require some architectural changes (separating module-documentation and tutorial-contributions from core API documentation).

As I heard you just recently choose MediaWiki for your new dev doc backed and done some work around it. So I think now one will want to bother with this idea.

> Ideally there's at least one "owner" of userhelp which keeps an eye on the changes, and a smallish group of frequent contributors. This group can pick up corrections/suggestions from the user comments. Typical too many cooks in the kitchen problem I guess. If you leave userhelp edits open to everybody, you get a dozen different writing styles, duplicate content, unreviewed incorrect information, etc.

This is a good idea to get the user help outdated as it got now.

Face it: there won't be any group constantly working on the user help.

I agree to make publication-approval mechanisms reserved for the user help "owner" so that no trash content will be showed to end users. But please let the people work on the user help when they what to and without having do ask you for permission to help you.

Resuming. OK keeping SS as the back end of the user help i also an good idea. A just got the info from the SS team that it got ported to 2.3 which is another plus for it. But as from my point of view the registration of editors in the user help has to be open.

Avatar
Ingo

Forum Moderator, 801 Posts

11 January 2009 at 3:28pm

> But please let the people work on the user help when they what to and without having do ask you for permission to help you.
Hm, the "asking for permission" thing worked quite well for translate.silverstripe.com - its a fairly informal way of stating your initial interest in userhelp (beyond just adding suggestions through the provided comment forms). The concept of a "group of owners/managers" for a certain technical or community aspect is pretty common in the opensource world - the "producing open source software" e-book is a good source for common approaches:
http://producingoss.com/en/social-infrastructure.html
http://producingoss.com/en/managing-volunteers.html#delegation
http://producingoss.com/en/managing-volunteers.html#territoriality
http://producingoss.com/en/share-management.html
Its not so much about fencing off ownership, rather than clarifying responsibilities and delegation. Mostly this group forms naturally once the project (userhelp) gets going, so nothing to worry too much about now.

Avatar
Howard

Community Member, 215 Posts

11 January 2009 at 10:53pm

Couldn't we use SS with the workflow module and have a group of people who can accept changes but changes can be made by anyone, thereby we get to use SS, anyone can make changes but we still have control over wether or not the changes are accepted.

Avatar
walec51

Community Member, 16 Posts

18 January 2009 at 4:41am

> Mostly this group forms naturally once the project (userhelp) gets going, so nothing to worry too much about now.

Well I have my doubts because I'm trying to get my hands on the user help's sources for about a 1 month now.

Could some one please tell me is it already on the SVN and if so where can I find it on open.silverstripe.org ?

I revised my plans for the user help and they look like this:

Stage 1 (next 18 days):

- Update parts of existing user help
- make an English dive in tutorial in to silverstripe in the web cast approach in a separate SilverStripe installation,

Stage 2 (no time limit)

- update rest of the user help
- translate the user help to polish
- make a Polish dive in tutorial in to silverstripe

But this all depends if I can get the sources of the user helps, which I've heard that are bundled and ready somewhere.

Avatar
Ingo

Forum Moderator, 801 Posts

21 January 2009 at 5:54pm

Hey Adam, I've put the sourcecode for userhelp in our public svn repo, and sent you login details as well as a database dump.
http://open.silverstripe.com/browser/projects/ss2help/trunk

I've suggested that you get the required template changes for new content structures done first, so we don't get into database content migration issues with the current live content. Once this code is reviewed and deployed, we can start content editing on the live system with an approval workflow in place. We've got a code freeze for userhelp internally now, but will continue to make smaller database content changes.

We're still figuring out this workflow of collaborating with the community on parts of our (previously internal) infrastructure, thoughts on how to streamline this and remove roadblocks are appreciated as always :)

In terms of translation of the userhelp content, the Translatable component should more stable on our current trunk now, but won't make it into the 2.3.0 release. We're hoping to get this into 2.3.1, so please hold off with any translations until then.

Happy coding!

Avatar
Ingo

Forum Moderator, 801 Posts

22 January 2009 at 4:58pm

Unfortunately I've been a bit rash about making promises about your work finding its way to userhelp.silverstripe.com - we've had some internal discussions, in which we decided to treat userhelp.silverstripe.com as an internal resource for the moment, and keep it simple.

You are of course welcome to take the PHP code from the project as an example on how to implement your own (polish?) version of userhelp, and reuse any of our free themes on silverstripe.org. We're generally open to link to external resources from appropriate places on silverstripe.org, but don't have to necessarily host it ourselves. Opensource is about distribution just as much as collaboration after all :)

We haven't discarded the option of hosting translations under userhelp completely, but the idea is at least on hold until we have a solid translatable implementation and workflow in a SilverStripe release.

We're still interested in some enhancements you suggested, but in a more modular format. Particularly an export of the whole website into a PDF handbook would be a handy module which could be applied to userhelp. There's a pdfgeneration module (http://open.silverstripe.com/browser/modules/pdfgeneration) which you could use a base for the implementation.

Let us know how you get on, thanks for your input!