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   3352 Views

Avatar
walec51

9 January 2009 at 12:23am Community Member, 16 Posts

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

9 January 2009 at 8:28am Forum Moderator, 801 Posts

> 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

9 January 2009 at 12:08pm Community Member, 16 Posts

> 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

11 January 2009 at 3:28pm Forum Moderator, 801 Posts

> 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

11 January 2009 at 10:53pm Community Member, 215 Posts

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

18 January 2009 at 4:41am Community Member, 16 Posts

> 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

21 January 2009 at 5:54pm Forum Moderator, 801 Posts

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

22 January 2009 at 4:58pm Forum Moderator, 801 Posts

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!