PW Manual

[Oliver]

As our studio is getting close to finishing another project, we are facing the challenge to provide our client with easily understandable materials or kind of a manual on how to manage content in PW.

As I guess that this happens from time to time to you guys around here, too, I wonder if it would make sense to collaborately work on a kind of manual document explaining key actions to be done for an editor. So there could be an open document or wiki providing texts in different languages and supportive images we all could use to e.g. turn it into a nice PDF or printed handbook (yes, some clients still like paging through paper) where we just have to replace images.

I don't think this work has to be done over and over again by each one of us for his own purpose. And I'm sure, all our clients would benefit from something like this. Also it would be a nice plus for everyone thinking about using PW the first time for a client project.

[Marty Walker]

I've been thinking of how to approach imparting the workings of a client's site to them. I do print design as well and I find generating PDFs a bit tedious especially if the content changes from site to site.

I had thought to tack on a /help section to the client site and use the csv importer to generate most of the topics and then modify as required.

[Oliver]

I was thinking of a shared base as a ressource for generating individual site-/client-specific versions from it or just link to it. In what format or media each of us provides the material to clients doesn't matter.

[Nico Knoll]

I guess this is a great idea. Because my school's new website will run with ProcessWire (I build it) and our teachers would probably love to have something like this in german

[Pete]

For the majority of areas where things would be the same this makes sense, but as soon as you come across custom templates (most non-basic websites I guess) then there will obviously need to be some work - that said I do like the idea of a collaborative base manual from which to customise.

[Nico Knoll]

But the most important thing is to show editors how they can edit pages generally I guess. Home to create a template and so on could be in the "advanced" part.

[Pete]

Indeed - basic editing is the key. Everything from logging in, creating pages, editing and deleting pages, TincMCE fields (just the basic set of buttons would be great) and other common fields from a standard installation would be great.

If we decide to go a bit further and write instructions on how to deal with date fields etc then that's not a problem as anything that's not relevant can be deleted on a per-client basis, but takes longer to add it every time

[teppo]

This is a great idea, folks! Of course there are various problems to solve (like has already been said - custom templates, not being too specific etc.) but most PW sites still have a whole lot of stuff in common

We've been planning to build something like this for our clients, and most likely still will, considering that most of them speak Finnish (and not providing any kind of guide in their own language is hardly an option.)

Anyway -- a wiki would be nice way to deal with this considering collaboration, translations and everything. I'd definitely be interested in participating in creating the material.

[ryan]

Does anyone have experience setting up/running a wiki like this? Drop me a note. I can setup an account here to host it.

[Nico Knoll]

@Ryan: Well, I never did it before, but I guess it shouldn't be that hard to setup a wiki. So I would try it

[pideluxe]

Would it not be better to integrate the manual in the backend in an pw-installation? So the editor could be informed when using the backend, maybe also with contextual help.

Why not use processwire itself for the manual? If wiki-style-linking is desired, a textformatter could be used to achieve this.

[Oliver]

Pidelux, I also think, a wiki like manual could absolutely be built on PW itself. And in view of contextual help: why shouldn't the manual provide alternative read access to its articles via json or xml, so the information could be used by e.g. a module providing contextual help in backend?

[Nico Knoll]

I like the idea of an alternative generated JSON version. But how could we use PW to create the manual in different languages? Is it working with Ryan's language plugin?

[charliez]

pbworks.com offers free wikis with limited capability but probably enougth for this.

I like the idea!

[teppo]

Great ideas here, but I'm still voting for putting up wiki site as a starting point. Developing something more sophisticated later on won't be much of a problem, but IMHO what we need now is first version - and we need it pretty quick, so that we can see how it starts gaining momentum.

When discussing the platform choices, keep in mind that most wiki platforms are exceptionally good at handling stuff like multiple editors, access restrictions and revision history - absolute necessities if we're going to have more people producing content. My experience comes mostly from MediaWiki, though, so that's what I'd suggest. It's ugly and kinda bloated but it does get things done

@charliez, that sounds great too, but wouldn't it provide some extra credibility if wiki site was running at manual.processwire.com or something similar? Though I'm not sure if this was what Ryan had in mind..

[Pete]

My main concern is another bit of software to maintain - I've got experience with MediaWiki but it's definitely not fun to run when it reaches a certain size. I also don't like having different logins for different software on the same website - it should be as easy as possible for users to contribute with just one login, which is where a lot of this falls down unfortunately.

Is there not something we could do with ProcessWire? I mean, how complicated are we thinking of going with the manual? I get that wikis are great because you can discuss the page that's being edited, plus there is a revision history, but aside from the revision history (at the moment!) this sounds like something you could achieve with a PW install and the comments module. In terms of a login system it should be easy enough to tie in the forum logins with PW users.

I'd actually say that we shouldn't rush into this. I like the ideas and the momentum but I would hate for us to use the wrong software for the job (not saying my suggestion is right either, I just don't really like MediaWiki as it's old and slow - there are likely other, newer systems out there that should be considered if we were to go down the wiki route).

Edit: I was only really reading the last post so I didn't spot all the other comments saying "why not use PW?" until just now

[apeisa]

Let's wait for few hours, Ryan releases his page revisions module for PW and let's build the damn wiki, right?

[ryan]

I'm not sure the software matters so much at this point, so long as it lets us get going quickly and covers the short-term collaborative needs. The focus in the beginning should be on the editors and their short term needs. Getting the content going is a lot harder than getting the software. Content is portable. Once the content is in a good place, then we're in a good spot to put it wherever it would best serve the users (while still keeping it collaborative).

PW was not designed as a Wiki, so it'll take some work to make it behave like one. That means somebody coding it before we can populate any content. I think the content has to come before the software here. (Though if the editors actually prefer to use PW as-is rather than a real Wiki, then we'll do that). If it were just me, I would probably use PW since I don't know my way around Wikis. But PW is a multi-purpose tool, and a Wiki is a single-purpose tool that designed for the exact purpose we are looking for.

Assuming a Wiki is a better environment for the editors, my opinion is that it's a good way to get things going short term. Moving it into a PW-powered Wiki longer term would be ideal. That way we could maximize the flexibility of the content… even providing JSON doc feeds to live PW installs like mentioned above.

If we've accomplished what we want to with the content, then converting and delivering it with PW will be the easy and fun part.

[Nico Knoll]

If nobody has started working on a PW wiki version I would start with it

[ryan]

Any idea what software looks interesting for this? I've also been meaning to check if there is any Wiki-type software that already integrates with IP.Board. I kind of doubt it, but just a 'nice to have'.

What do you guys think about hostname? Here are a few ideas:

• processwire.org (already setup)
  
• processwire.net (already setup)
  
• manual.processwire.com
  
• man.processwire.com (unix style)
  
• readme.processwire.com
  
• rtfm.processwire.com
  
• wiki.processwire.com
  

[SiNNuT]

Any idea what software looks interesting for this? I've also been meaning to check if there is any Wiki-type software that already integrates with IP.Board. I kind of doubt it, but just a 'nice to have'.

What do you guys think about hostname? Here are a few ideas:

• processwire.org (already setup)
  
• processwire.net (already setup)
  
• manual.processwire.com
  
• man.processwire.com (unix style)
  
• readme.processwire.com
  
• rtfm.processwire.com
  
• wiki.processwire.com
  

Ryan,

Some googling reveals this: http://www.ipbwiki.com/ which seems to connect/integrate IP.Board and Mediawiki.

As for hostnames: i personally quite like rtfm.processwire.com (there's already rtfm.modx.com) but i'm not sure that everybody can appreciate this.

Some other options:

• userguide.processwire.com
  
• guide.processwire.com
  

[DaveP]

I love

rtfm.processwire.com

but wiki.processwire.com would probably be the logical choice.

[Nico Knoll]

wiki.processwire.com +1

And I would use MediaWiki, too. I mean this forum doesn't use PW as well so why should wiki? And with the plugin found by SiNNuTs it would perfectly with just one login

[Oliver]

rtfm.processwire.com is the modx way, isn't it? But I like this one, still.

[ryan]

I think you are right that rtfm is the modx way. I don't really want to seem like we're trying to copy them on that. We probably need a term that doesn't necessarily label it as the comprehensive manual, because we have the main site docs. I kind of like the one sinnut mentioned "guide", since it doesn't infer itself to be an all-inclusive manual and it also seems more clearly distinguished from API, which is the named use by the docs on the main site. I also like "wiki", except that it says more about the software running it than it does about the content, and I'm not sure wiki means anything to the intended audience.

@Pete are you okay with MediaWiki or can you think of something better? I know you mentioned some concerns about it as things get large. I have a feeling we won't be getting that large (at least not by Wikipedia standards). And having the IPB->MediaWiki integration with the thing Sinnut mentioned seems like it would solve the multiple account issue. Still, I have no experience with MediaWiki, and it sounds like you do, so don't want to jump into it if it's going to be a bear.