Wiki Maintenance

[shawn_a]

Ok we need some major updates and upgrades to the wiki.

Upgrades
Noone is going to use an authoring system that is not easy to use. I don't even use it, it aggravates the heck out of me. So I would love to see our wiki easier to to maintain, a better wysiwyg editor perhaps or markdown support, and better previewing. Also a better interface.

Updates
I would love some input in transforming the wiki into a better document set.

We need to designate a clear plan on how it should be structured.
Most importantly is how to keep it up to date with new features and workarounds, and keep version specific content segregated. Right now there is a myriad of comments about this and that version. It would be nice to have some kind info boxes in sections about the difference in versions. This is where footnotes should be used notating that functionality described applies to these versions and special notes for older versions or deprecated functions.

We want to keep content, but segregate it so the wiki does not have old information in the content.

I think the sections need to be redone ( great work has been done so far on the main index, much more needs to be done )

Sections need to be clearly defined.
Indexes should be as concise as possible, they should not be sitemaps. Limit clutter etc.

Structure
Getting Started
Installation
Upgrading
FAQ

Basics
Advanced
Theming
Plugins
Programming ( API )
Tutorials
Step Throughs ( With actual step indicators and step by step illustration, not paragraphs and paragraphs describing, but showing this is essential with our international audience )
Cheatsheets
Glossary - eg. wtf is a hook ?

Usability
Since its a wiki everything should link to everything else. If something says turn on "permalinks", then this should link to permalinks information.

Are we using camelcase ? how is autolinking setup ?

Quality and legibility.
Easy thumbnailing, zooming.
Clear and structured content, proper use of Headings etc.
All images/screens should be pixel perfect PNGs ( and for the love of god, use anti aliasing for screenshots)
Make use of figures, images do not always have to be inline.

Input
Suggestions ?
Specific update info required ?

I think the wiki is accurate as of ~3.0-3.1
So it is a bit behind on 3.2.x features

[shawn_a]

eg of what bothers me when looking for information.
Headers that run on.
Installation

eg.

Code:

Installation on a Web Server or a Local Server
Migrating, Moving and Uploading Complete Sites
Server requirements and Apache Modules
Upgrading to the Latest Version of GetSimple
Guidance for Specific Hosting Companies

Too much information. Granted these are usually auto generated by the titles of the pages or the first header.


An actual section

Code:

Installation on a Web Server or a Local Server
Step by Step Install Procedure
Installing on a local server
  Installation
  Known Problems
  Moving from local server to a 'live' site
Links

Would be much better as

Code:

Installation
  On web hosts
  Local server
Migration

[shawn_a]

Obviously we have to go through the entire thing and plan anything like that, but its just a guideline.

Also I think it would be pretty useful to have a side menu navigation.

[shawn_a]

FYI
Github issues are labelled with "documentation" to track things that need to be documented.

https://github.com/GetSimpleCMS/GetSimpl...ate=closed

This includes changes in functionality, new and deprecated functionality, gsconfig, hooks, filters, etc.

[shawn_a]

I added some tables to hooks/actions and fixed up some information.

[datiswous]

I had some ideas about improvement, but they include extra Dokuwiki plugins.
I thought the following plugins might be useful:

1. Like you said, better editor:
https://www.dokuwiki.org/plugin:ckgedit
and/or:
https://www.dokuwiki.org/plugin:fckglite

It seems there's a filebrowser included with it, I don't like the current one

I don't know why you would want Markdown. Is Markdown not comparable with wiki-language?

2. Tabinclude

The Tabinclude plugin creates a tab-control for selected wiki pages. By clicking a tab, a DokuWiki page appears on the site using AJAX.

I think this is handy for navigation through pages in the sections. For example: all 5 pages from section Themes navigatable via tabs.
Although I think this can also be made with the Wrap plugin, but probably without AJAX support.

3. https://www.dokuwiki.org/plugin:wrap

Wrap wiki text inside containers (divs or spans) and give them a class (choose from a variety of preset classes), a width and/or a language with its associated text direction.

Although it might be a bit advanced, it has a lot of possibilities.

4. https://www.dokuwiki.org/plugin:anchor

Normally, you can only link to a wiki page, or a specific section header. This is impractical when header names are long, or you expect that they might change. This plugin lets you create links to any part of your page.

5. https://www.dokuwiki.org/plugin:authorlist

Displays all contributors/authors of a wikipage.

I know there is already a central page for this info, but it can still be handy for people who only do edits of certain parts to know who to talk to about edits and do agreements etc.

I didn't actually test these. I just have read about them. Also, I only did choose the ones which are tested with the latest version of Dokuwiki.

[datiswous]

* Apart section about Plugin documentation maybe. Plugins can (also) link to that. Would be nice to have more info on specific widely used plugins, like Custum Fields (there's no Wikipedia page about Custom Fields, only a lot of info how it is integrated in Wordpress).

* Some/every Part of GS-admin could have a help/wiki link to relevant section(s) in wiki. This might also encourage people to read the wiki before posting here.

* https://www.dokuwiki.org/faq:sectionedit
the edit-buttons appear at the end of a “headline” section. But only at certain headings. Would be nice to include more (h4,h5,h6, etc). This means editing becomes easier because of smaller chunks of content.

[Timbow]

Much needed discussion I think. Good. let me weigh in too, but first of all let me say the discussion should be bigger still. GetSimple works really, really well. It is a fine piece of kit and the developers are doing a cracking job, but the project overall is behind and lacking in many ways:

• The default themes are out of date, back and front end.
  
• The default content could be improved
  
• The GS.info site design seems good to me but much of the content is out of date.
  
• Press releases have never been done since the beginning.
  
• The whole 'route in' whereby users progress from taking a casual glance at GS, to looking in more detail, to spending half an hour trying it out, to beginning to learn to use it should be looked at and made smooth and easy. that applies to the site, the core program, the forum and the wiki.
  
• And the wiki? Yes it's really important to make it good, so back on topic for this thread these are my thoughts.
  

Yes, the dokuwiki software could work better. Really good contribution from datiswous. We have no auto linking. All the links need to be put in manually. At the moment you navigate the wiki by looking down the index page like you would a paper manual but you should be able to progress through categories, keywords and searches and with a bigger wiki you would have to.

The structure - The Primary division in the index is by User Level (casual, beginner, user, developer) and that is the best primary structure but we lack secondary underlying categories. I mean if you want info on say the CKEditor the wiki pages are scattered through all the main sections and there is no way of progressing through them. The dokuwiki manual says that pages should be arranged and categorised in a logical directory tree ('namespace' in wiki-speak), whereas our pages are not. I am not clear how useful it would be and reorganising them would break every internal link through the wiki and from the main site and from the forum and from the GS Backend and you wouldn't want to try to do it with ordinary editing rights.

We have to accept that the wiki will always be a version behind the program unless releases are delayed while the documentation is prepared which would be dumb in our case.

Really, really good to flag up items the developers think might need documenting. I haven't always known what has changed or where to look. Remember not every change needs documentation. I have deleted a lot of statements like 'New in 3.0 is the slightly different...'

Plugins - YES. I was answering an email query last week and explaining that at least half the difficulty in learning to use GS is learning your way around Extend and the several hundred plugins. I still don't know it myself. We cannot have a user guide for Extend so what is the best way to deal with this? I was thinking maybe we need a series of articles like

• Three ways to Blog with GS
  
• Images Sliders and Galleries in GS
  
• Getting feedback by emails and commenting in GS
  

We already have a couple like 'How to do SEO in GS' and 'Extra Security in GS'. I think they are useful.

Glossary, yes we have the beginning of one

FAQ - Excellent idea. Real FAQ (that are actually asked from time to time) please. I will start a thread to collect some.

Is there a case for splitting up the documentation? Into say

1. Learning GS
   
2. Reference
   

Got to go.

[shawn_a]

Thanks,
I appreciate the plugin suggestions datiswous, I have not touched dw in like 5 years and its now coming back to me seeing some of those.

" Some/every Part of GS-admin could have a help/wiki link to relevant section(s) in wiki"

excellent suggestion, I am sure the info is there but making sure its structured like the actual GUI would be nice.

[shawn_a]

I will probably at some point add actual reference generated from the docblocks in our php to document actual theme_functions and template_functions.

[hameau]

... add actual reference generated from the docblocks in our php to document actual theme_functions and template_functions.

An excellent step forwards. Just being able to find built-in functions would be useful for many purposes, with the potential to become a great reference resource.

This is something I missed when I gave up on Wolf (phpDocumentor).

[datiswous]

The structure - The Primary division in the index is by User Level (casual, beginner, user, developer) and that is the best primary structure but we lack secondary underlying categories. I mean if you want info on say the CKEditor the wiki pages are scattered through all the main sections and there is no way of progressing through them. The dokuwiki manual says that pages should be arranged and categorised in a logical directory tree ('namespace' in wiki-speak), whereas our pages are not. I am not clear how useful it would be and reorganising them would break every internal link through the wiki and from the main site and from the forum and from the GS Backend and you wouldn't want to try to do it with ordinary editing rights.

I think we can add tagging. This way you can see the pages with for example tag ckeditor, but they still stay in their categories.

I think namespace ordering is already done for some older pages. Example:

http://get-simple.info/wiki/how_to:page_editing
http://get-simple.info/wiki/how_to:theme_editor

With Namespaces pages may be better organised and there are some plugins using it, like
nssearch and nspages .
Some navigation plugins don't need it, like this plugin: pagequery.

* Stickies in Installation & Setup and General Questions and Problems about looking in wiki and or reading faq.
* Maybe a better plan/way(and/or plugin) for translation is needed

[shawn_a]

I think namespaces are for separating content, so if we wanted plugins in the wiki they would be managed under their own namespace. But imam not entirely sure.

[datiswous]

I think namespaces are for separating content, so if we wanted plugins in the wiki they would be managed under their own namespace. But imam not entirely sure.

A namespace is similar to a directory or folder, while pagenames are similar to files. In DokuWiki you can use namespaces to categorize your pages. For names of namespaces the same restrictions hold as for pagenames.

https://www.dokuwiki.org/namespaces

On the Wiki sitemap you can see that the sitemap is also ordered in namespaces. Part of the wiki is ordered that way, the rest not.

[datiswous]

Btw. What Dokuwiki version is this site using?

[n00dles101]

DokuWiki version: Release 2012-10-13 "Adora Belle"

[datiswous]

http://get-simple.info/wiki/

Section Admin Reference -> Theme Tab

and

Section Themes -> Ready-Made Themes

could be merged.

Section Themes could be renamed to Theme creation and/or merged with section Advanced Theming

[shawn_a]

They should not be merged, theme tab is specific to the tabs for the interface documentation.

The tab sections should be contained in a new section specifically for the ui, with concepts and advanced details in outlinks.

[datiswous]

Ok fine.

Btw. is there a way to download the full wiki? Could be handy for offline work. Also, people would be able to test certain things on the wiki (layout etc.) and give suggestions etc. Playground is a bit small for that.

[shawn_a]

Yeah I think there is , I'll look into it.

[Everyone]

I see some discrepancy in plugins' tabs & menus:

(3.1+) If you want to add multiple links for your plugin, you can use the optional parameter action:

PHP Code:

add_action('xxxxxx-sidebar','createSideMenu',array('your-plugin-filename','Menu Text', 'my-action')); 


This way a new parameter action=my-action is added to the link and you can determine which link was clicked.
(...)
main function (here hello_world_show) would look like this:

PHP Code:

function hello_world_show() {
  if (@$_GET['action'] == 'setup') {
    ...
  } else if (@$_GET['action'] == 'show') {
    ...
  }
} 


Except that no action in $_GET is ever created. Rather $_GET gets an empty my-action key. That given, proper code to handle multiple actions would be something along these lines:

PHP Code:

function hello_world_show()
{
    if( array_key_exists( 'show', $_GET ) ) {
        ...
    }
    elseif( array_key_exists( 'setup', $_GET ) ) {
        ...
    }
    elseif( array_key_exists( 'my-action', $_GET ) ) {
        ...
    }
    else {
        ...
    }
} 


Unless this is a bug that needs to be patched, am I free to go ahead and correct it?

[shawn_a]

yeah, isset might be faster though.

[Everyone]

I'm having trouble with the fragment about adding side bar links to two different tabs, where page_type parameter needs to be set dynamically.

Since there's no $_GET['action'], this part of the code is wrong:

PHP Code:

@$_GET['id'] == $thisfile && @$_GET['action'] == 'setup' ? 'plugins' : 'theme' 


but I don't know how to get this right. Even without that I don't really understand what is going on here. Is there a way to check what page_type is currently visible?

[Everyone]

I've come up with this:

PHP Code:

function dynamic_page_type( array $pairs )
{
    foreach( $pairs as $page_type => $action )
    {
        if( isset( $_GET[ $action ] ) ){
            return $page_type;
        }
    }
} 


So if there are two actions like those:

PHP Code:

add_action( 'pages-sidebar', 'createSideMenu', array( $thisfile, 'Pages Option', 'pages_opt' ) );
add_action( 'plugins-sidebar', 'createSideMenu', array( $thisfile, 'Plugins Option', 'plugins_opt' ) ); 


that need to be visible and active on pages tab and plugins tab accordingly, the register_plugin() would look like this:

PHP Code:

register_plugin(
    $thisfile,    # Plugin id
    'MyPlugin',    # Plugin name
    '1.0.0',     # Plugin version
    'John Hancock',            # Plugin author
    'http://website.com',    # author website
    'A plugin that does things.',    # Plugin description
    
    # page type - on which admin tab to display
    dynamic_page_type( array( 'pages' => 'pages_opt', 'plugins' => 'plugins_opt' ) ),
                
    'run_MyPlugin'    # main function (administration)
); 


Maybe GS should have something like that natively?

[shawn_a]

Yeah this implementation is terrible.