Photo Organizer

"Once Shop Categories and Shop Items are defined, you will have to define your Photo Items, by defining for each photo the available Shop Items with pricing information. You can use the Shop Item Generator to automatically generate Photo Items for your folders." -- that's in the help page relating to the shop.

The funny thing is that I don't really understand the shop stuff either -- I never sat down to figure it out, but IMO it's overly complicated.

But back to your original point, yes, the documentation is indeed lacking in many (most?) areas, and indeed is only getting worse under my stewardship, as PO's been getting new features and other changes that are poorly documented, if at all.

But documentation is *hard*, and I'm spending all of my limited time on the code (and some testing) these days.

It might be a good idea to start a documentation wiki. This way others can help documenting the way PO works. I wouldn't mind spending some time here and there changing or adding information to such a wiki. The starting point could be the current documentation.

Also, such a wiki would allow for documenting some internals of the PO code

The main wiki (http://po.shaftnet.org/) should theoretically anyone with an account on the bug tracker to log in and make changes.

I just created a top-level documentation page.

I guess the first step is to migrate PO's online help pages over, then start adding more, but I'm not touching it until I get the 2.33 release blocker tasks finished. Only 50 more files to go!

Can't edit when logged in:

"This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong."

I think it is wrong ;-)

It should be fixed now. There was a mismatch between the wiki's group list and the bugtracker's.

Yup, it works now.

I added the first page of the help to check it out. I have a HTML to Wiki converter installed on my laptop, so when I get some time soon I'll try to convert the PO help files to Wiki markup and insert them into the wiki. This should give us a starting point.

I moved the documentation stuff into its own wiki namespace, and created a proper sidebar for the table of contents. Thanks for doing this work, and please add your name to the contributors list.

Thanks,

I just pulled the help through html2wiki and uploaded the pages.

I fixed some links here and there and also repaired some formatting where html2wiki was confused (the xml and php code examples).

There are some links to the example sites (in the integrated documentation these point your own installation). I redirected these to Balint's demo site, but these need to be changed to a local demonstation site. I added a note about this in the pages.

It feels a bit narcistic to add my own name to the contributers list, especially for something as simple as this. But if the maintainer asks you, what can you do but comply? ;-)

Added more sections to the documentation Wiki.

Documentation now split up into:

- Installation (added by Solomon)
- User Documentation
- Developer Documentation
- External Documentation

Solomon: the developer documentation also contains a section on "Contributing". I made something up there so you might want to sanity check that to see if it matches your development model. Also, might it be a good idea to add me to Flyspray as a developer, instead of just a viewer/bug reporter? Then I can take ownership of this issue.

Done, and done. Do your worst. :)

Your changes look sane.

I think the current documentation focus should be re-syncing the user documentation with the current/upcoming (ie -stable) PO release.

I'm doing some rewrites already, starting at the top.

The high-level developer documentation will be nice to have, but it's lower-priority, and (I hope) will be obselete by the time it's written. :)

Finally, we need to give some thought to converting the documentation wiki back to straight HTML so a static snapshot can be bundled with a PO release -- we need offline help.

NOTE: I assume that with off-line help, you indicate the help files that gets distributed with PO, i.e. the current integrated help of PO.

I agree with the off-line help, this is needed. This does not necessarily need to be the same as the online Wiki but may have a link to the online wiki for people who want to know more.

For now we can use the Wiki to generate the off-line help in a collaborative fashion. If we can find an automated way to convert the wiki into static html then we have a powerful setup. I'm sure there are tools for this: http://www.google.com/search?hl=en&q=wiki2html

- wiki2html for wikimedia: http://tools.wikimedia.de/~merphant/wiki2html/

In the long run we might have the off-line help be specific for each PO release and be maintained separate from the Wiki. In this way the wiki can be much more than the off-line help. Parts from the wiki can then be incorporated in the off-line help and we could incorporate the off-line help of the versions into the wiki.

This may need a bit more thinking. We might want to look around to other projects. MythTv and Ivtv for example use wikis for creating documentation as well. We might want to check out how they are dealing with this.

Regarding the developer docs. For me to get an good understanding of PO, I need to look at these things anyway. So why not try to capture what I learn in the wiki at the same time? For example, in order to understand the shop I need to look at the code as well as trying things out.

P.S. Thanks for upgrading the account.

When I think a bit more about it, I feel we need to keep the wiki documentation and integrated (off-line) documentation separate (in the long run).

Here is why I think this:
- The integrated documentation is specific for the installed version, the wiki will likely be for all (current/recent) versions (containing notes when something is specific to certain versions).
- The integrated documentation should likely only contain a user manual (including admininstration) regarding an installed version of PO (so everything that can be done through the web interface of PO).
- The installation docs are not part of the integrated documentation, but they are part of the distribution (e.g. in the INSTALL file) and again are version specific.
- Documentation in the wiki may contain examples of how people use PO and how to set it up for that use.
- User documentation in the wiki may link to other non-user documentation in the wiki.
- It is probably difficult to fix a constantly changing wiki to a single PO release.

(The latter three make it hard to take snapshots from the wiki for the integrated help).

I know it sounds horrible to have to maintain two sets of documentation, but one is strongly tied to PO releases where the other is a community effort (based on an associative knowledge sharing tool).

Finally, this does not mean that at the moment we can not use the wiki to create/upgrade the current integrated documentation, but in the longer run there will likely be divergence. So if we can create a baseline documentation in the wiki now, we can take a snapshot of it to create the integrated documentation. From then on they will need to be maintained separately.

Checking MythTV, I think this is exactly what they are doing:

"Integrated" help is here: http://www.mythtv.org/modules.php?name=MythInstall
And the wiki is here: http://www.mythtv.org/wiki/index.php/Main_Page

But we may want to ask them what they actually do.

In all fairness, MythTV has quite a few more developers (and users) than Photo Organizer. They can afford the luxury of separate documentation; they have the time and manpower to do it.

Meanwhile, I don't see why a full snapshot of the documentation wiki at the time of release would be a problem; Presumably the wiki would be kept up-to-date as new features are added, and sanity-checked just prior to release. A documentation snapshot would be made at that time, and bundled/integrated with the download. We could even keep a copy of that snapshot online for posperity.

Obviously the "help" button would only link to what's relevant to the user at the time, but keeping even one set of documentation up-to-date is difficult; two more than doubly so. The current bundled, but non-integrated documentation is *very* obselete right now, with the exception of the install document. This is why I want a single authoritative documentation source, and we'll bundle/integrate an up-to-date-as-possible snapshot with each release.

Oh, I found a tool designed to export dokuwiki in particular:

http://sourceforge.net/project/showfiles.php?group_id=109345&package_id=161552&release_id=366868

It seems to work well enough, and even groks namespaces properly -- I exported only the documentation.

http://www.shaftnet.org/users/pizza/po-export/podoc-sidebar.html

Obviously it'll need work before it's usable, but I'd much rather the information be *there* first, and pretty second. Heck, if the programmers do their job right, the documentation won't ever be necessary. :)

Great, good you have found a tool for this.

I agree, for the time being, updating the wiki and exporting snapshots from there is a usable solution. If and when this would break down in the future we can see if we need to go for another solution.

Would it be an idea to have a namespace in the wiki for just the user manual (i.e. the integrated or off-line documentation in PO) and another namespace for more general documentation on PO? This would allow for capturing whatever knowledge is gained on PO without cluttering the user manual with information that is not relevant for the end user. It would then also be best to keep the user documentation self contained (i.e. the user documentation pages may only link to the user documentation itself and nowhere else. However, they can of course be linked to from other parts of the wiki.)

Thus, I agree with your way forward which is snapshotting the wiki for the integrated help.

Okay, we're getting closer to the actual 2.34 release. All features are in, so the documentation updates can now commence.

We need:

* Updated install docs (for -rc1)
* Updated PR docs (things like feature lists, requirements, etc)
* Updated user docs (all new features, remove all obselete features, and add a "workflow" example)
* Rewrite on-line help (based on new user docs)
* Updated devel docs (can wait until -rc_final)

I take that back; new features are still being added. It's sadly inevitable due to the fact that I'm the only one coding anything, and my needs take precedence over things like internationalization. :) So, add these to the above list:

* "What's changed" document for those upgrading. (store removal!)
* Permission model documentation (especially about how public/protected/private now work)
* Explanation of what it means to be a "client" of another user.

Install/requirements docs are updated, as is the login/registration page and the bulk update page. The config file is now documented too.

All traces of the 'shop' are removed, although there's a lot of other stuff to update still.

The new client workflow needs documenting.
The current security/permission model needs documenting.