Cleaning up documentation, wiki and setting up a mechanism to avoid duplicates/old data going ahead

[pliablepixels]

Invitation to discuss and hopefully close quickly. I can get to work after that
@knnniggett @SteveGilvarry @kylejohnson @connortechnology (and whoever else needs to be linked, please add)

Organizing documentation, removing dead-links, repeated and outdated information, setting up a framework to keep things clean going ahead.

I'd be happy to get this going, after any comments/edits from you.
It isn't too much work once someone gets into it.

Overall assumptions:

1. Kyle sets up the webhook so any documentation PR made at https://github.com/ZoneMinder/ZoneMinder/tree/master/docs that is merged automatically builds into http://zoneminder.readthedocs.org/en/latest -- this encourages good quality documents that are accepted by ZM devs to always show up and avoid readthedocs becoming stale

2. Kyle sets up http://zoneminder.readthedocs.org/en/stable/ to point to stable releases

3. When a user visits //zoneminder.readthedocs.org/ it does NOT redirect to latest. We have 2 links: Browse latest stable release documentation and Browse latest development snapshot documentation - folks can bookmark whichever link they want. The top left header should either show "master" or "X.YY.ZZ Stable" to differentiate.

4. I'd recommend stable releases use the current CSS theme and the master snapshot document uses any other sphinx CSS (there are many templates) stylesheet to always visually differentiate. maybe blue=stable/ green=master or something

Cleaning up the Wiki

a) https://wiki.zoneminder.com/Welcome

(I don't have write access to this page)

We put a notice here this wiki is mostly contributed generated documentation. Users should refer to the following official documents for ZoneMinder

http://zoneminder.readthedocs.org/en/stable/ - documentation related to stable releases

http://zoneminder.readthedocs.org/en/latest - documentation that reflects the latest master snapshots.

b) https://wiki.zoneminder.com/Documentation
We completely remove the contents here - its dated and confusing. readthedocs/latest has all of this and updated. I don't recommend putting in a deprecated noticed - most often people miss the notice and many people maintain links to parts here which are wrong. Better to remove

We just add a link there pointing to readthedocs/stable

c) https://wiki.zoneminder.com/FAQ
We keep this here. However, we actually have a more updated version here http://zoneminder.readthedocs.org/en/latest/faq.html

My suggestion is to remove the current FAQ at the wiki, point to the readthedocs "latest" FAQ and also add a note to the wiki saying "In addition to the official FAQ, feel free to add more user tips here". And then I can add some more tips. This tells people that the readthedocs FAQ is the main one, but if someone wants to add a tip thats not part of readthedocs, they can add it there. Classic examples would be stuff like this:https://wiki.zoneminder.com/Various_Learnings_from_getting_Zomeminder_1.28.1_working_well_on_Ubuntu_Server_14.04

If people post stuff that is really good, ZM contributors can always merge into the official FAQ any notify the user

d) https://wiki.zoneminder.com/Help:Contents
We reword this to point to readthedocs as well as the forum

e) https://wiki.zoneminder.com/Contents

We rename this to "Helpful resources contributed by users"
(Note we no longer have "Documentation" - it was always confusing to have both)

Inside this, we keep FAQ, Supported, Third Party, and Other Documentation, CCTV laws - delete the rest.
We add a new section called "Installation Procedure"

f) Installation procedure handling

In the "Installation Procedure" of point e) we link to readthedocs/installation

We also let users add to this section, and add this as a subpage
https://wiki.zoneminder.com/Common_Issues_with_Zoneminder_Installation_on_Ubuntu

We request bbunge to take ownership of https://github.com/ZoneMinder/ZoneMinder/blob/master/docs/installationguide/ubuntu.rst and request the following:

1. He updates this document instead of the wiki for new procedures/updates
2. He can always add sub pages to the wiki for stuff that should not be in the official rst file. Such as "Common Problems"

[pliablepixels]

I'm out for 2 weeks starting tomorrow - returning on Dec 6 -I'll get to work right after (or before, depending on my mood) - so I'm hoping we can conclude on an approach. I think a lot of ZM's issues are to do with documentation structure.

[pliablepixels]

I'm out for 2 weeks starting tomorrow - returning on Dec 6 -I'll get to work right after (or before, depending on my mood) - so I'm hoping we can conclude on an approach. I think a lot of ZM's issues are to do with documentation structure.

[knight-of-ni]

This all sounds good to me. I don't have edit permission to wiki welcome page either. If anyone does, it would be @kylejohnson .

[knight-of-ni]

This all sounds good to me. I don't have edit permission to wiki welcome page either. If anyone does, it would be @kylejohnson .

[pliablepixels]

Sounds good @knnniggett
I assume no additional comments == everyone else is ok?

@kylejohnson - before I start, there are some dependencies on you (refer to points 1-4, and let me know if you have any comments)

[pliablepixels]

Sounds good @knnniggett
I assume no additional comments == everyone else is ok?

@kylejohnson - before I start, there are some dependencies on you (refer to points 1-4, and let me know if you have any comments)

[kylejohnson]

@pliablepixels Sounds good to me. I'll work on getting the /stable and /latest links right. I'm also a fan of using the color themes to differentiate which branch you're on, but I'm not sure how easy that is to do (I'll find out).

[kylejohnson]

@pliablepixels Sounds good to me. I'll work on getting the /stable and /latest links right. I'm also a fan of using the color themes to differentiate which branch you're on, but I'm not sure how easy that is to do (I'll find out).

[pliablepixels]

@kylejohnson

1. I don't have access to https://wiki.zoneminder.com/Welcome - can you grant access?
2. I don't have delete access to pages - I've marked them to be removed, but can't do it myself -
   To be deleted:
   https://wiki.zoneminder.com/Help:Contents
   https://wiki.zoneminder.com/Documentation
3. The navigation on the sidebar needs to be corrected as well - Documentation to be removed, Contents to be renamed "User Contributions"
4. https://wiki.zoneminder.com/Sitesupport-url needs to be edited to point to whatever you want

@knnniggett - would you like to sync with Bill on taking over ubuntu.rst and doing a document PR? (refer to first post)

[pliablepixels]

@kylejohnson

1. I don't have access to https://wiki.zoneminder.com/Welcome - can you grant access?
2. I don't have delete access to pages - I've marked them to be removed, but can't do it myself -
   To be deleted:
   https://wiki.zoneminder.com/Help:Contents
   https://wiki.zoneminder.com/Documentation
3. The navigation on the sidebar needs to be corrected as well - Documentation to be removed, Contents to be renamed "User Contributions"
4. https://wiki.zoneminder.com/Sitesupport-url needs to be edited to point to whatever you want

@knnniggett - would you like to sync with Bill on taking over ubuntu.rst and doing a document PR? (refer to first post)

[pliablepixels]

I'm done with my changes. The items that are pending:
a) @kylejohnson - /stable and /latest setup
b) @kylejohnson - help in wrapping up stuff I don't have access to #1169 (comment)
c) @knnniggett - advise on what needs to be done for bbunge to update ubuntu.rst and migrate from his wiki to the official guide.

[pliablepixels]

I'm done with my changes. The items that are pending:
a) @kylejohnson - /stable and /latest setup
b) @kylejohnson - help in wrapping up stuff I don't have access to #1169 (comment)
c) @knnniggett - advise on what needs to be done for bbunge to update ubuntu.rst and migrate from his wiki to the official guide.

[kylejohnson]

@pliablepixels /stable and /latest should now work. Please confirm.

[kylejohnson]

@pliablepixels /stable and /latest should now work. Please confirm.

[pliablepixels]

@kylejohnson - @SteveGilvarry just merged my updated master changes to doc here #1193

When we now go to http://zoneminder.readthedocs.org/en/latest/ it loads up the master version
When we now go to http://zoneminder.readthedocs.org/en/stable/ it loads up the stable version and with a different color.

So confirmed it works.

But: I'm wondering how to put back the version number. I removed the hardcoded version in conf.py -- that results in it not showing 1.28.1 in both which is correct. I can add a function for conf.py to automatically get the version # from git describe -- but it only shows the last tagged release (1.28)

Any ideas on how to return the string as 'master' for the latest tree and 'git describe response' for the stable path? @SteveGilvarry ?

[pliablepixels]

@kylejohnson - @SteveGilvarry just merged my updated master changes to doc here #1193

When we now go to http://zoneminder.readthedocs.org/en/latest/ it loads up the master version
When we now go to http://zoneminder.readthedocs.org/en/stable/ it loads up the stable version and with a different color.

So confirmed it works.

But: I'm wondering how to put back the version number. I removed the hardcoded version in conf.py -- that results in it not showing 1.28.1 in both which is correct. I can add a function for conf.py to automatically get the version # from git describe -- but it only shows the last tagged release (1.28)

Any ideas on how to return the string as 'master' for the latest tree and 'git describe response' for the stable path? @SteveGilvarry ?

[SteveGilvarry]

No can do according to everything I read. latest and stable are it, then you can publish versions also.
http://sgzoneminder.readthedocs.org/en/latest/ http://sgzoneminder.readthedocs.org/en/v1.28.1/

PS I don't know what you did to the stylesheet on latest but prefer readthedocs one.

[SteveGilvarry]

No can do according to everything I read. latest and stable are it, then you can publish versions also.
http://sgzoneminder.readthedocs.org/en/latest/ http://sgzoneminder.readthedocs.org/en/v1.28.1/

PS I don't know what you did to the stylesheet on latest but prefer readthedocs one.

[pliablepixels]

It seems to me the "default" theme was applied to master instead of the rtd theme (http://sphinx-doc.org/theming.html) - this happened because I imported "default.css" in the stylesheet. I'll explore how to switch themes depending on latest/stable - we should have different themes for them

[pliablepixels]

It seems to me the "default" theme was applied to master instead of the rtd theme (http://sphinx-doc.org/theming.html) - this happened because I imported "default.css" in the stylesheet. I'll explore how to switch themes depending on latest/stable - we should have different themes for them

[pliablepixels]

closing this - we are all set here

[pliablepixels]

closing this - we are all set here