Hey patrick, thanks for the quick repsonse. I am also unclear about what documentation is for implementers and what is for developers... I dont think it's a solid line.

As a result, and for the sake of simplicity, I think the consensus is that we need a single source for the docs. From a laymans' perspective, I think the best solution is possibly to put all documentation about a specific release (unless it is sensitive or transient) on the release wiki (or some other central location) and then enhance the main splash page to help implementers find the most common needs. The problem is that all of the wiki pages (including developer-specific pages) are duplicated on the release-specific wiki but in a pre-1.6 form which is just extra confusing. Implementers are provided with the higher levels docs but they are out of date. Similarly, it is confusing that up-to-date docs are located in a heirarchy called "old documentation".

The alternative is to delete unnecessary pages from the release wiki but this sounds undesirable. Embedding one with the other wont work when we want to freeze the documentation for each release.

I am planning some implementer discussions to see what docs they need, I can also ask if there are any that are distracting and we could discuss moving those to the main cspace wiki for developers only.

In the meantime I'm going to create links between the two pages and attempt to rectify them. If there are priorities in this area let me know. Otherwise it will probably be chronological to start.

Thanks again,
Heather

On Jul 18, 2011, at 2:24 PM, "Patrick Schmitz" wrote:

One of the challenges is separating developer documentation from implementer (deployer) documentation, from end-user documentation. I.e., helping the core team to know when they should put something where. It is not always clear to me when the audience is a developer versus a user (are Chris Pott, Joe Slag, and Glen Jackson developers? Not formally on the project, but in reality, and in some discussions, they are). There are some useful definitions at the high level of the documentation structure, but a common workflow is to search for related pages, and go from there to add in more documentation. This search often bypasses the high-level structure, and so folks may end up adding to the wrong spot. Moreover, end users and implementers are using search as well, and may get conflicting docs (old and new) in the result. I have heard from at least one implementer who was confused by this. His comment was something to the effect that: "the documentation I needed was hidden, but I eventually found it."

Perhaps marking all the old pages as old (as you suggest) would help. Perhaps we (at least I) also need a little tutorial on the design of the documentation structure,. so we know where to edit what.

AIUI, developer documentation (e.g., all the Service REST APIs and payloads) are exclusively located on the main wiki. A search for REST on the wiki space linked below returns only the glossary term. This is okay, although perhaps we should at least link back to developer docs from the other (there is a high-profile link from the main Developer doc page to the release docs). However, for something like Reporting (which I have been working on), it is not all that obvious to me where the developer docs end and the end-user docs start. Ditto for batch processing jobs.

Thanks for taking this on Heather - I know it can seem thankless, but it does make a big difference to users, and it is worth the effort to get this straightened out.

Patrick

________________________________

From: tech-bounces@lists.collectionspace.org [mailto:tech-bounces@lists.collectionspace.org] On Behalf Of Heather Hart
Sent: Monday, July 18, 2011 10:44 AM
To: 'CollectionSpace Tech list' ?[tech@lists.collectionspace.org]?
Subject: [Tech] Updating documentation

Hi everyone,

As I'm going through the documentation and trying to pull it together I need some help from you guys. I noticed that some people are still posting updated documentation to the main cspace wiki (these are the wiki pages with “/display/collectionspace/” in the URL). However, as of release 1.6 all new documentation needs to be added to the "current documentation" wiki that was created: http://wiki.collectionspace.org/display/UNRELEASED/CollectionSpace+Relea...

The /display/collectionspace wiki has been migrated and archived as "Old Documentation" and is being preserved for posterity, but anything posted to that wiki will not be migrated to the release-specific documentation (unless done manually) and will not be accessible to implementers (or developers) except through search.

During a discussion with the team leads, we decided that we want to keep the current documentation wiki and associated workflow. If there is no objection, I am going to lock down the "old documentation" wiki on the main cspace wiki so that it is uneditable and possibly add a "this is for reference only and does not apply to the new version. To update documentation please see: (link)" message to the top of the pages.

In some cases, I think that the two different pages may have been updated at different times so it isn't always clear which information is correct. To make sure that all updated documentation is on the UNRELEASED wiki, I will be asking those of you who were the most recent editors of both versions of the page to work together to rectify the two versions if I can't work it out for myself. This will be ongoing.

If you have any questions, please let me know or ask me tomorrow at standup. If there is any documentation that anyone feels should not be included in the release wikis and needs a home on the main cspace wiki, please let me know and we can work that out.

Thanks everyone for your help,

Heather