[OPEN-ILS-DEV] 2.3 Documentation progress.

[Justin Hopkins]

On Aug 9, 2012, at 9:14 AM, Soulliere, Robert wrote:

> The "assume it is all good from the last version" approach works for me and makes things easier for everyone involved.

<sarcasm>
This is why I always follow the 1.6 documentation when I'm trying to figure out how something works
</sarcasm>

In all seriousness though, there are quite a few times that I find myself consulting older documentation just because it's the only version that included the section I'm looking for. It's sometimes (often) wrong but is at least a good start. I do generally agree that it's ok to port forward all documentation from the previous version but I also think it's going to be time saving for members of DIG to mark potentially suspect sections for review by developers and other DIG members.

It's obviously a good thing to let community members at large find these errors but the fact is that many people aren't as good as others when it comes to dealing with problems as they arise. It may not be apparent to them that the documentation is wrong and that it's not something else that's causing their problem. It's not usual to people to look to the documentation to solve their problems and if the documentation *is* the problem it may be more than the initiate user can tolerate.

I hate to propose a solution by creating another problem but here's a blue sky idea: (I see that Alexey has said something similar)

When new/beta documentation is posted each section that was ported from the previous version has a "ported from version X.X" tag. Also, every section (whether ported or not) has a "This section is under review. Is it accurate? (radio buttons)" kind of system. This would allow us to remove the ported tag when, say, 10 people "vote" and 90% of them say it's accurate. We could keep the question/feedback section there and re-flag the section as suspect if people vote it down.

This would be something that I could see being implemented in the new Drupal site - and I have some Drupal experience so I'd be willing to chip in to help build it if others think it could be useful.

Cheers,
Justin