Built in docs for admin and users

[Joss]

Just a very vague idea here.

The idea is to create a set of help pages in the back end. Not the wonderful notes system from Soma (which is ever useful), but a centralised system that is partly automated.

So, for each module two sets of docs are written by the developer - admin and user.

When a module is installed, these are automatically added to the backend help system. This is permissions based, so the superuser can decide who can see which set, plus make exceptions for specific modules. This includes switching some of the docs off entirely if it is thought they might confuse or are simply not needed. (Might even allow devs to pre set this if their mod adds functionality where docs are unlikely to be needed)

Additional notes can be added manually to each of the docs at either the head or tail so the admin can add anything specific to that particular website. When modules are updated (which might include updates to their docs) these additional notes are not affected and still work.

Extra docs can then be added by the admin for site specific functionality that are not related to a specific module. 

The entire lot can be viewed in the admin as a cohesive set or can be viewed as in context help in a popup.

Sorry!

This system does put a pile of work on module developers (and even more on Ryan), but the result if worked out properly could help the day to day usage of the admin enormously and makes ProcessWire even more accessible to potential clients

The two sets are key here. On other systems where help is built in, it is often aimed at the admin not the user, so the poor user gets flooded with information they might not understand and do not have the permissions to use even if they do. This way, each user, admin or other, just gets the bits they need which is a lot cleaner!

[yellowled]

This system does put a pile of work on module developers (and even more on Ryan), but the result if worked out properly could help the day to day usage of the admin enormously and makes ProcessWire even more accessible to potential clients

Here's what usually happens in my experience: I spend about a (paid) day documenting the specific setup of PW sites for clients, proof-reading and carefully crafting nice PDFs, which I then mail to the client. Clients usually go “Oh, this is great! We have or own manual tailored to our needs which we can reference any time we don't remember what you told us in the CMS training! I'll print out copies for everyone right now!”

Weeks or months later I get a call. “Erm, we kind of forgot how this-and-that works, and we were wondering if you could come in for another CMS training? We haven't used the system in a while and most users forgot what they learned in the training.” – “Well, you always have the documentation I wrote for you …?” – “Yeah, about that … could you send us another copy of the PDF, please?”

The alternative is clients that go “Nah, we don't need documentation, we'll get along with the backend just fine.” And they do, because PW can be pretty self-explanatory.

Bottom line, documentation is important (and PW is documented pretty well already, compared to other CMSs out there). But a lot of end users (again, just in my experience) tend not to read it, because they prefer a human expert to tell them how what they specifically need works. (Which is why questions get asked over and over again in forums, in my opinion.)

I'm not sure a documentation integrated in the backend would really work and thus be worth the effort or overhead. (In fact, I don't even know if it would be an overhead.) Also, there's the risk of inconsistent (some things being documented very well, others not so much) and outdated documentation, which I feel is almost worse than no documentation at all. Oh, and translations, of course.

[PhotoWebMax]

I like the idea of a having a module(s) available for docs. Even though there are so many ways of building sites with PW there must be a solid basis for docs in module form? Maybe have a custom content input Field for site developers and end site editors that would allow them to customize specific site details. In the end I think such a system might be a welcome time saver for busy site developers. 

Documentation always seems like the unwanted guest at the (open source development) dinner party. Making it easier, more concise and effective is a real plus in my book. 

[teppo]

Like the idea, but it really does seem a bit vague. Would love to see this taken further, though

I was also wondering about translations (like @yellowled said earlier) and the roles; you mentioned "admin" and "user", but I can think of quite a few cases where those won't be enough (some modules define a bunch of permissions, use cases may vary between roles or groups of users, etc.)

Would you see this as something that is bundled with the module as a file (perhaps something like modulename.docs.md) or a module setting, or what?

Should superuser be able to completely override the docs without touching files in the module directory? Mostly thinking of cases where we might require something specific -- or just felt that a different angle would better fit particular client.

Sorry, it's getting late here and my head seems to be full of questions

Documentation always seems like the unwanted guest at the (open source development) dinner party. Making it easier, more concise and effective is a real plus in my book. 

I guess this depends on your point of view. In terms of docs Linux tools tend to be lightyears ahead their proprietary competitors, and a lot of open source projects I've worked with have had (at least) quite extensive code-level documentation (i.e. comments). For most parts ProcessWire is a good example of this

[Joss]

Morning Teppo!

Well, in keeping with the way ProcessWire works this would be pages.

So....

Probably the module would include two .md files as default:

ModuleName.userdoc.md

ModuleName.admindoc.md

At install time, these are converted to pages if the docs module is installed.

Working backwards... If the docs module is installed later, then it scans the modules directories and adds any of those files.

That is the really boring basics.

Administrating Docs

Since these are now pages, this becomes a little easier. 

Under Admin in the tree there is a new parent - Docs. Under that two sub-parents - Admin and User.

In each are all the relevant pages.

Permissions are associated with the admin and user parents which are inherited by their child pages. These permissions govern who can see the docs; by default only admin can edit. 

Each page has the relevant md file imported into a CKeditor field. This means that the admin can customise the documentation if it is relevant. They can also add extra fields to the templates if they want to change the way docs are viewed. It would be as customizable as anything else in PW.

Permissions can be changed for individual pages if there are several roles who need access to different things. Pages can be published and unpublished, as normal, so that if there is no need for particular docs they are not cluttering up the system.

Languages

If the various module developers are brave enough to do translations of docs, then maybe these can appear on language tabs. Perhaps some markup in the MD file identifies that this next bit is in a different language and what language it is in. A tab is created to match on import. That means the default doc language of the file also needs to be identified, of course. (Bit cheeky to assume it would be English!)

Possibly needs the ability for the admin to add their own translations too.

So lots of customizable bits there.

Because this is the normal page system, the admin can add new pages talking about other stuff.

If, for some mad reason, a third set of docs is required, or even a fourth, then another parent can be made - "Authors" or "Telephone Sanitisers" perhaps. Maybe even a publically available parent. Other pages can then be added under there.

Viewing Docs

The docs module would install its own templates, template files and a unique ckeditor field (so it does not muck up any existing bits).  It would install its own search page too.

It would show the docs in the language of the setup, if they are available, or it would show the default language of each doc if a specific language is not available. 

The docs ultimate parent page is the docs home page. It would list available docs on a permissions basis and include search (results on permissions basis).

Access to this would be a link on the main menu bar.

Linking to Docs

This I am not so sure about.

if a module has a "settings" page of some sort or some other setup procedurers, it makes sense for the module dev to make sure there are links written into the right part of the docs.

The site admin, however, should perhaps have some way of adding links to admin forms to specific help pages. That would be something in the template , I would guess. 

Very complicated Docs

Some docs may be very complicated and should be on several pages. This can use Ryan's multi-page markup system, though it will need something in the markdown doc that it can recognise and convert.

So, most of this uses bits that are already available in PW - the biggest bit is the import.

[lisandi]

Doing Documentation is not an easy thing and there shold be standards so that all those docs don't look cluttered all over.

If you have time have alook how it is done in TYPO3.

Here the extension developer provided and OpenOffice

 

What extension is used for displaying the manuals in the documentation section?

Manuals for TYPO3 extensions are traditionally written using Open Office Writer. An extension called ter_doc converts these manuals to DocBook and then run different XSLT sheets to produce the various output formats.

If you want to display Open Office Writer documents, use the Documents Suite - it offers a similar functionality for Open Office Writer files.

This works pretty good as you can list those documents in thebackend if needed.

The docs itself have standardized sections so that you immediately know if it is for setting up , maintaining, or editing stuff etc and it includes a reference with all possible settings. As a developer you usually have a look to those docs but not as an editor as they contain the technical stuff too and people who are editors get shocked. So first you need to clear out for whom you will need docs.

Editors
Admins
Developers
Designers

Than you should use a methode which is easy to handle for developers to, as usually developers which can write good understandable documentations for admins and editors are very very rare.

Than you need to think about the ballast of a documentatin which is integrated and where actually nobody can contribute.

So IMHO the much much better solution with much less ballast for core and modules whould be to keep those docs external on a centralized server where everyone can contribute and write, auggest, review and this place you link with a module to the backend of processwire - or even to the frontend.

Now you can categories pages in those 4 Groups and in that module only the pages you actually want to list would be shown. It only would need to check what Modules have been installed. Beside that you would be able to translate all the documentation into multiple languages as a global effort. Many German customers don't like an English documentation, the same like Americans don't like a German one.

Also you could ed lots of multimedia stuff i.e. the existing videos in that appoach.

For those who want to have an option to read their docs also offline could store it locally for later usage.

Nevertheless this documentatin should follow always the same base structure otherwise the Processwire documentation would look like a total chaos.

Another huge benefit of an online centralized documentation is the fact that it can be kept very easily. If using even something like Google Docs you would have even Versioning in there so you could see what changes have been made over the time. I would not reinvent wheels but simply use the tools which are already available - mostly free - to accomplish that job.

Using much less developer resources to maintain the whole stuff

with Versioning you have a very good review and can manage different authors

it is possible to integrate images and videos etc.

...Andi

[Joss]

That is different documentation. This is about having specific docs relating to a completed site that would be site specific.

[lisandi]

hmm Joss - What should be the purpose as all this site specific stuff would need to be created over and over again, unless you duplicate a site profile which already includes the docs. In our experience most of the stuff especially editors would need can get covered by extension/module/app documentation which is in a standardised format and which can be included into the sites depending on what modules got installed.

The thing you propose here seems to be a whole lot of work as no collaboration would be possible and it had been mentioned already in many threads that developers have other preferences than writing docs or wasting time with that stuff, and they are right.

Actually you could include some specific stuff still into the doc.

i.e.

The site is calling an iFrame with the docs in the backend or the frontend or it is pulling an rss depending on what modules got installed. Beside that the already integrated notes do a great job IMHO but you could also include another nicer looking doc with images again i.e. from YOUR server so that at least you could reduce your own workload in writing those docs while you won't be able at all to collaborate with others or get help in Translations of thedocs. Don't underestimate Translations - its a whole lot of work and Editors often don't speak English or German and site owners usually like to have their docs in their languages.

With a centralized online solution this is easy to accomplish as you can collaborate with people from all around the world.

[Pete]

Joss is taking about specifically tailored sites where the customer's solution would be different each time, different templates and field names etc so the instructions would be different.

I usually have a base document and change screenshots and field names to suit the project but I like the idea of having it in the admin.

[lisandi]

Well if it is such specific I would put it in a module as such kind of documentation usually goes into a print out manual or PDF and not at all needs to be included into the admin area. It blows up the site unecessarily and makes it heavy especially when you add screenshots images etc.

Like you said if it is such specific keep it specific for those who don't write manuals as pdf for their customers. IMHO much more important is the general usage of a processwire site and this can be managed very easily like I described above and it does not blow up the sites with unnecessary ballast. It gets loaded from a central server includes translatations and would make the job for devs and manual writers much easier. Beside that a great documentation about the possibilities of Processwire categories for the 4 Group of users would be available - similar to a good book!

With the "sepcialized" doumentation you woul do good to keep it on your server and connect it to that as described. So you can make changes and improvements to the doumentation whithout the need to access sites and usually there are many things you simply could reuse on most of your sites. With taging you could put them into an order.

Beside that it would be also a great place to inform customers about news, security fixes, improvements, or even special offers as you could add them on your server. This could drive also more revenue to your business! and to Processwire!

[Joss]

My clients are obviously different from your clients. They do not want to know what the software is, or where the website for the software is. They have no interest in security upgrades and so on - that is what they pay me for.

All I am talking about here is a certain amount of basic user information that comes with specific modules (core or third party) which is loaded into the system and can be added to if needed for site specific reasons.

Nothing huge, nothing heavy, just a simple use and update system that the developer can customise on a client to client basis without having to worry about external repositories, loads of unnecessary pictures, videos or all those other things that my clients simply don't have the time to use. 

All they want is something so when they are adding to the few areas of the site they have been given access to, they can say, "what the hell is this Hanna thingy?" and click the Docs button to find out. That is all.

You have to remember that my clients are tiny companies whose main concern is their bricks and mortar operation and not their website. They do not update daily or even weekly, maybe not even monthly, so they forget how to do things. This is just a simple system to address that basic need, but that can be expanded for more complex solutions and even involve things like editorial guidelines, staff contact lists or anything else that is completely non-technical. (Things that the client would definitely NOT want on some central resource )

[lisandi]

Hi Joss this was actually what I was talking about at first place. The customers are not so different I think. You actually will have 4 kind of customers - from our experience. I mentioned them already above. All of them have their own specific needs in what they want to learn about the system.

Developers: They are interested in the code, settings, configuration options, on how to extend a certain module etc - as we do outsourcing here to this is one kind of clientel we are having

Designers: They are less interested in the coding but much more in how they can design a template with that module. They often need to know about configuration settings but usually won't code in the core of a module.

Admins: This is actually a group which every site has as they need to maintain a site. I know that many agencies don't care so much about maintenance and security after they delivered a site. Well we are for sure different here as we care a lot about it to make our customers happy with a site for a long time. So we teach an admin how to check for security updates and if he can't do the upgrade by himself - well than he cancontact us or another developer. Also all information about how to create users, groups, roles and access rights etc belongs into that section as well as how to make a backup of a site.

Editors: They are the ones you are probably talking about. They usually don't need to know much about the functionailty of a module - in terms of configuration, coding, design or administration, but they need to know in how to make usage of a certain module. This is why the Tutorials and Manuals for Editors will look very different from all the others. They usually contain screenshots to make it easier for them to follow the tutorials.

We here have all 4 kind of clients and there is also a 5th Group which actually are all those "site self builders - but they more or less can read in all 4 sections.

Nevertheless is an integrated solution where you have to upload your stuff to a certain site a huge ballast, which will make the sites or even the core or modules unnecessarily big. Therefore the much better solution is actually to keep those manuals centralized as I pointed out already with the huge benefits you will gain by doing that.

All our Editors until now (since 2002) wanted to have their Manuals in their language! and this was in 90% of the cases not in English! Even the Admin Manuals had to be translated - especially for German and Thai spoken customers. Having an online solution where everyone can contribute, this is an easy task, while writing all the stuff by your self over and over again, without the chance to update it regularly is a huge hazzle.
 

"All I am talking about here is a certain amount of basic user information that comes with specific modules (core or third party) which is loaded into the system and can be added to if needed for site specific reasons."

You are talking about modules and even core functionallity which is somekind different about what Pete was talking. While you talk about general information he was writing of specific stuff. Both are different kind of stuff with different needs.

In what language you will provide that information? English? How do you translate that information to make it accessible for people which don't understand or can read english?

Like said with an centralized online solution this is very very easy to handle!

 

All they want is something so when they are adding to the few areas of the site they have been given access to, they can say, "what the hell is this Hanna thingy?" and click the Docs button to find out. That is all.

Let's take our Thai customers as an example:

They want to know what that Hanna thingy is and click a button and have an english explanation what they hardly (mostly not at all) can understand. So where do those people getthe translation of that what you provide for the Hanna Thingy?

This actually sounds more like a small question beside a certain field with additional information for that field. We have something like that also in TYPO3 and to be honest most customers don't use it! But on the other hand it is able to be localized. As itis information provided to a module that information will be always the same for all people using that specific module and therefore a global approach where you can contribute a translation i.e. to Thai Language or German Language etc, will help all other developers to which are using that module. - Check out the Poodle discussion on how to do it!
 

You have to remember that my clients are tiny companies whose main concern is their bricks and mortar operation and not their website.

That's why things like you propose here should go into a module which people who need an English and not other Language Explanation can install it or not. The same way the other option I propose would go into a module to not blowing up the core of processwire or the modules itself.
 

Things that the client would definitely NOT want on some central resource

Of course they want to have it accessible from within their backend. That is also what we do in other systems to inform customers about functionailty and other information just from within the backend. They actually not even know that the information gets maintained centralized. Those who have an Intranet solution with no web access can integrate an offline documentation.

The most important part I see in all of this is in how you will handle the translations and the updates of those documents! Perhaps you can explain that a bit more!

1. For whom should this documentation be? - I think it will be Endusers of a site - which means Editors - am I right, perhaps admins?
2. Who is supposed to write the base documentation? - I guess the developers
3. In what language should they write their documentation for those Editors? - I guess in English, even he has only German customers. No English customers he/she will write in German I guess!
4. Who will handle the translations of those informations?
5. Where will be those informations be handled/stored? - Inside the core and inside the modules I guess which will blow them up!
6. How do you handle updates which come with modules - i.e. a Blog Module or SEO module comes with additional features?
7. How gets the translations of those updated modules get stored and handled?
   
   It would be nice if you could explain how a German or Thai Enduser with no or limited English Knowledge make usage of it!
8. Where does all that base information gets stored? - I mean the original "English" or "German" Version

[Joss]

I already talked about translations earlier, if the developer of the module or whatever has time/money/inclination. I personally would not force anyone to supply multilingual docs.

Translations are always a problem with me. I spent many years producing corporate and TV programmes in multiple languages - up to fifty or sixty in some cases - and was used to very high quality idiomatic translations done by the best technical and interpretive translators around. 

But they cost huge amounts of money to do. (We used to do translations for Philips electrical for an annual staff day full of videos, workbooks and so on. The budget just for the translations was over $100,000 before we started recording)

The one thing I have noticed about translations in the open source world of, especially, complex technical documentation, but non-tech as well, is that much of it is just dreadful. 

But then, the source material is often interesting as well! (fun, though)

ProcessWire is unusual in that Ryan is a very fluid writer and his initial docs are high quality. 

The problem seems to be that techy people are happy to squint and read through interesting translations to get what they want.

Clients, who are putting up the money, are not - and quite rightly so.

I was involved with a Joomla project a few years ago (just on the sidelines) where the devs passed over the translations for a couple of the plugins that were done centrally by one of the mass translation systems. The client just found them amateurish and started losing faith in the entire project. Thankfully, there was enough budget and I had a couple of my old voice overs sort them out, and the client's faith was restored.

So, I would be very cautious of using any centralised system where I did not have proper control over what my client saw and exactly how it was presented.

The whole point of my suggestion is that the basic docs, having been installed locally, can then be edited and played around with by the dev to customise them for that particular installation, taking account of that client's particular needs and so on, including the addition of any other info that is peculiar to that client and may be private.

I was not trying to suggest something that needs an entire central server, huge amounts of maintenance, cost, mass collaboration or anything else so complicated or unwieldy. 

[LostKobrakai]

I think the big difference between the points of you both is in the definition of docs. 

Lisandi sees them as documentation for the CMS as a whole. So there are docs about the UI, modules, for admins, for designer and so on. Because each of them has to somehow work with the cms, while each need to learn different stuff. I would consider most of this information as bloat for the actual cms. Designers and Developers do have enough resources here on the site and clients should have no hassle with the basic UI functionality of processwire after a bit of initial introduction. 

Joss on the other hand is talking about a documentation the developer/designer is setting up only for the user/client. This is very much sitespecific as even most modules can be used differently on each page, not talking about different sitetemplates. One could see them as site maintainance guidelines / helpers.

[Joss]

Thanks, LostKobrakai, and that is the difference. And the site specific use was the intention of my thread.

[lisandi]

Joss on the other hand is talking about a documentation the developer/designer is setting up only for the user/client. This is very much sitespecific as even most modules can be used differently on each page,

And because it is such specific it belongs into a custom module and not as something which shoudl go into modules or core! Otherwise those things get bloated up as you said LostKobraKai. Nevertheless would need also such a custom module a way to translate those docs1

The whole point of my suggestion is that the basic docs, having been installed locally, can then be edited and played around with by the dev to customise them for that particular installation, taking account of that client's particular needs and so on

Everything what has to be installed locally especially for devs is causing more work for devs. Better would be to have those gerenal stuff available on a centralized server incl translations where everyone can collaborate with others and share their translations. Than if a dev needs a customized version he can i.e. download the specific part and customize it even in the translations.

where I did not have proper control over what my client saw

Who says that you don't have the proper control?

You as an Processwire Integrator are developing a site for a customer the same as I deveolp one.

We both have same but also different modules installed

now those modules can read the files incl. their translations from the centralised version where the extension developers and translators i.e. me for thai or german would collaborate. Or a devwho is not so good in English provides a great German docu und you (if you can understand german) or anybody else could translate it into english so that people who can't understand german would understand it.

Now you have the option - either you take the doc as is or you overwrite the stuff you want to present to the customer, which means you create a localized version wich fits only your very specific site needs. Of course it will be your time and effort to modify it - incl the translations, but if the centralized docs are very well structured than it is very easy actually to pull out the necessary stuff even from the translations which would safe other developers even when they want to create a localized version a lot of time.

Reiniventing wheels is never a good solution and the centralized repository with those general docs which can be downloaded locally is much easier to maintain than any local version of docs which only blow up the stuff. At the end it would be the decision of the INtegrator to use the provided General Version incl their translations which are available - getting them directly without blowing up sites, or loading the customized version of a doc which would blow up only your site of the customer.

Translations are always a problem with me. I spent many years producing corporate and TV programmes in multiple languages - up to fifty or sixty in some cases - and was used to very high quality idiomatic translations done by the best technical and interpretive translators around. 

But they cost huge amounts of money to do

Inspire to share! should be the motto instead! and it would reduce costs for everyone working with Processwire a lot! especially when they need a translation into another language than English! - Collaboration is the way to go IMHO!

[Joss]

And because it is such specific it belongs into a custom module and not as something which shoudl go into modules or core! Otherwise those things get bloated up as you said LostKobraKai. Nevertheless would need also such a custom module a way to translate those docs1

You simply do not listen.

NOTHING here is about the core.

This is about a module idea.

It is completely optional.

It does not need to be part of any translation system if that is not wanted.

It does not even need to be taken up by module developers if they do not have the time.

So, will you stop hijacking my ideas my introducing things that I was not talking about. You simply bring discussions to a grinding halt.

Consider this topic now closed

[PhotoWebMax]

Tangential thread direction or not: I still like the idea...

[Macrura]

@joss - like your idea; just spent 2 hrs making PDF files with screenshots, arrows and callouts for a client so they can go in and start editing their site..

of course I could make some a custom admin page and put a sidebar link to documentation;

but an all-in-one dedicated module would be nice where you could add pages to some part of the tree for all of the docs and then have the module generate the welcome screen for the docs, with list view...

(sorry to post after you closed this)..

[Joss]

Sorry to cause confusion.

Basically I was telling another member that the subject was closed, rather than I was going to technically close the thread - it does not really warrant closing the thread. A wonderful case of idiomatic British meets international forum speak.

I am happy to continue chatting about the very basic and simple idea I first proposed, but I will not be discussing a long-winded, over complicated, over centralised system that no one has time or inclination to manage. 

That should be discussed in another thread should people be interested.

[arjen]

Sounds like a good plan. How would you visualize this in the backend Joss?

[Joss]

The idea is that initially, on module installation (or something like that) it imports the associated docs into the document page tree. That tree can be edited, added to and so on as normal.

When it comes down to viewing, this is permission based, but essentially it is like a very simple baby doc site.

One thought I had is that with various editor permissions on a page by page basis you could allow users to view a doc, or add notes to a doc or edit a doc. The middle one is particularly useful if users want to add little reminders or explanations without being able to edit the core page.

[arjen]

So small chunks of information related to a module - or perhaps to a specific page (template)? Like a small introduction were to put a news-article? What is the "document page tree"? 

I often thought about a tour or joyride through the pagetree. Simple steps like: how to insert an image? Or: where do I put a newsarticle?

[Joss]

You need to read my earlier posts!

[arjen]

You're right I got tangled up by the client posts and didn't grap your original post.

This is for developers and (perhaps more advanced users). Still seems like a great idea, nonetheless I don't really understand the document page tree you mentioned.