CI User Guide question

[eluser]jdfwarrior[/eluser]
[quote author="Colin Williams" date="1255505054"]Here's my thought on the process. Three tracks that largely overlap.

I. Design

A. Develop a new IA for the User Guide. Yes, we all know and love the current design, but it doesn't fully account for: Extended examples, function references, source view, discussions, etc. We don't need to start from scratch, just grow.
B. Create a visual design implementing the IA.
C. Develop templates/front-end code.

II. Content

A. Port existing user guide to the new IA.
B. Ongoing content creating by moderators + community.

III. Development

A. Use a CMS to implement IA, design and content.

Writing and maintaining a hybrid restricted-access-wiki-with-moderated-comments-addenda would be a non-trivial task.

I can think of a few CMSs that provide this out-of-the-box.[/quote]

I like the CMS idea..

[eluser]jedd[/eluser]
Well, yes, quite.

I think we all agree that a CMS is a really nice idea. I just don't (to use the vernacular) see how we can get there from here. Hence I had been thinking about the problem in terms of the two-stage approach, as I detailed earlier.

Given the nature of EL's flagship product, I can't imagine a reality where they would be keen to introduce a NIH CMS to their site. Nor is the conspicuous absence of comment on the topic terribly encouraging.

Colin, if a new CMS wasn't a likelihood, would you still be interested in doing anything around the extant user_guide source - a static content only effort, I mean?

I'm not au fait with the EE documentation - does that use the same style as the CI one? If so, I can't imagine EL would be too keen to mung up the CI one and therefore take it away from the 'corporate standard'. Same goes for all those third party contributions that used the available CI-stylesheet - I don't expect they'd be willing to re-engineer.

[eluser]Colin Williams[/eluser]
I see. I wasn't really considering the project being a property of EL at all--now or in the future. Totally controlled by a group of community members: Conceived, produced and hosted.

Colin, if a new CMS wasn’t a likelihood, would you still be interested in doing anything around the extant user_guide source - a static content only effort, I mean?

Certainly.

[eluser]jedd[/eluser]
Ooh, okay. I hadn't even entertained that idea. Partly the logistics, partly the maintenance (eg. tracking changes from the CI svn user_guide), partly the social / political problems with forking CI, partly the challenge of letting people know the resource exists and getting / keeping traffic there. I've been pondering the idea the past few hours, however.

I think anyone that's had more than a casual fling with the CI user guide knows that it has its shortcomings. I really want to work on fixing those - which includes things like the simple syntactical and consistency of examples stuff through to providing this CMS-ish php.net-ish user-contrib-partials-etc for each function stuff.

Every time I try to resolve those two thoughts, I wind up thinking we can't move forward until EL Inc gives some hint as to what they intend to do, what they'd be willing to host, what level of community collaboration they'd entertain.

[eluser]jdfwarrior[/eluser]
[quote author="jedd" date="1255645997"]Ooh, okay. I hadn't even entertained that idea. Partly the logistics, partly the maintenance (eg. tracking changes from the CI svn user_guide), partly the social / political problems with forking CI, partly the challenge of letting people know the resource exists and getting / keeping traffic there. I've been pondering the idea the past few hours, however.

I think anyone that's had more than a casual fling with the CI user guide knows that it has its shortcomings. I really want to work on fixing those - which includes things like the simple syntactical and consistency of examples stuff through to providing this CMS-ish php.net-ish user-contrib-partials-etc for each function stuff.

Every time I try to resolve those two thoughts, I wind up thinking we can't move forward until EL Inc gives some hint as to what they intend to do, what they'd be willing to host, what level of community collaboration they'd entertain.[/quote]

I doubt we get any help from the EL team. Don't mean this rudely, no offense if any of the EL guys read this, but Derek has already said that's he's too busy to mess with a lot of this User Guide stuff (see his reply again on page 2 of this thread). If we were changing a few small things, then he could have done it, otherwise, he said it would take too long to fix. We could probably the system we are wanting rather easily. Preferably with CodeIgniter by just taking the current user guide, setting it up via CI where each page in the distributed user guide is used as a view, then adding the comment functionality and such at the bottom of the views. It would require us making updates to the static pages when updates were required, but it could get things going quickly.

[eluser]InsiteFX[/eluser]
Hi guys,

I have been reading on what you all have to save about the user guide and my idea on this is that the user guide should be split into different parts as a project.

1 ) Basic Information
2 ) Installation and Setup
3 ) Introduction to CodeIgniter
4 ) General Topics
5 ) Class Reference
6 ) Helper Reference
7 ) Additional Resources

Assign the above to project groups.

This way users that are working on the user guide project can be assigned to a part of the user guide to work on.

Users that want to submit updates etc to the project would need to post it to one of the above topics.

As far as a CMS or design it all in CodeIgniter, I would also break this up into a project group.

As far as a web site I can supply that for you, it has unlimited everthing!

it is running:
PHP 5.2.6
MySQL 4.1.22. Standard
Apache 2.0.63

Yes I would be glad to help out on this in any way that I can.

Enjoy
InsiteFX

[eluser]jdfwarrior[/eluser]
@InsiteFX: I highly doubt hosting will be an issue. I dont know that I particularly like the idea of changing the structure of it. I like the simple drop box like CI has now and how everything is clearly labeled.

I do know of one other thing that I think would be nice, expanding from Insite's idea of an "Additional Resources" category, and all of us being able to add screencasts and such that we found useful for learning CI there.

[eluser]Derek Allard[/eluser]
I think this is a noble project. Thanks for undertaking it. There are some questions as to how EllisLab would feel about everything. I can't speak for EllisLab, but for me, I like the idea of static HTML as it lowers the bar for who can edit them, and also is convenient for subversion and for packing up and distributing with CI.

I've already committed that we'll look at getting user comments into the CI docs (ala expressionengine.com/docs and PHP.net) but that likely won't happen until EE2 is out (we're announcing a release date at the end of the month).

and all of us being able to add screencasts and such that we found useful for learning CI there.

If you have anything to add don't hesitate to make them available to the community and let us know of your intentions to share them with the CI community. We'll add them to the tutorials page beside the other casts.

[eluser]jdfwarrior[/eluser]
As far as being easier to distribute, there could always be a mechanism that would take the dynamic content and build the same package that's passed around now, but I think the static would be better for now.

Glad to see your still checking in on us Derek Since you are still checking in, quick question, if we got a community based (and of course you guys would have access to it as well) user guide up and going and up to date and such, what would be the possibility that it could become the primary user guide? One of the things that we've been kicking around is the fact that, even if we maintain it properly, without exposure, it would more than likely be a failed project. If we got a good, working project, where we could allow code examples and comments, etc, do you think EL would ever link to it instead?

[eluser]Derek Allard[/eluser]
I don't think it would make sense for CI to defer to external documentation do you? EL would have no control over the quality or direction of it. So link to it instead seems unlikely. Now then, if the project did get of sufficient quality then of course we'd want the community to have access to it.

For legal purposes I'd imagine anything we distribute would need to be clear of any intellectual property concerns (ie: what if 1 of 876 people who contributed to the guide didn't want us to share their work?). Do you have a mechanism in place for that?