Documentation/Dashboard/Ideastorm

Infrastructure

Ideas for improving the documentation infrastructure. This can be new toolset proposals, reusing existing tools that are not being used effectively, wiki extensions and so on.

One Purpose - One Wiki

I think mixing Project organisation with End User documentation as actually done is bad. We (i.e. the doc project) should have "our own" wiki. And it should be clearly target group oriented and not project oriented (as the actual). This would lift quality and usability and hopefully usage (and therefore motivation for contribution). And I don't believe that administrating two separated wikis will double admin time as there will be less need/effort to harmonize the two target groups (developers vs. doc people).

I dont think this is a good idea for the following reasons:

There are not just two groups of content. There is are at least the following groups: User Documentation. Advanced User Documentation (API), Internal Development Documentation, Project/Effort Progress Documentation, Marketing
Those are not easily separated: There are huge overlaps between:
- User Documentation. Advanced User Documentation (API)
- Advanced User Documentation (API), Internal Development Documentation
- Internal Development Documentation, Project/Effort Progress Documentation
- Project/Effort Progress Documentation, Marketing

Even if current pages could be seperated in different groups (which would be a huge effort) there would be a lot of duplicate content, contradicting content and outdated content.

Also namespacing is easy in Wikis: Everything in Category:Documentation and subcategories is yours. The problem is that there are currently ~2400 pages that are in no category. That needs to be fixed otherwise the wiki quality will degrade. There needs to be an coordinated effort to move this stuff into categories.

--B michaelsen 09:51, 11 November 2009 (UTC)

MindMap

During the OOoCon20009 Doc presentation, Sophie requested a MindMap extension for the MediaWiki.

Which MindMap is this? Sophie mentioned one that WikiPedia uses, but I've not been able to find out which one it is. --ccornell 12:00, 8 November 2009 (UTC)
The one I had in mind (map ;) was wikimindmap [1] --sophie

Next/Prev Page at Bottom

Pet peeve, here: reaching the bottom of a long page in one of the Guides, and having to navigate back to the top, in order to get to the next page.--TJ 09:38, 5 November 2009 (UTC)

This was experimented with, but... for some reason, I cannot remember exactly why, it wasn't implemented. We could definitely look at it again. --ccornell 12:01, 8 November 2009 (UTC)

Move Material from Docs Website to Wiki

Many (most?) legacy pages on Docs website would be much easier to keep up to date if on the wiki: things like the list of PDFs of user guides (and the PDFs themselves). Get as much out of CVS as possible. --jeanweber 11 November 2009

Usability

just a little brain dump:

wiki documents should be given states (e.g. draft/published, similar to oooauthors, but not identical as in the wiki there is no need to retract a document)
- This can be done with the FlaggedRevs extension. I've installed it, but not enabled it as I have some technical probs to resolve first. --ccornell 11:57, 8 November 2009 (UTC)
end users should by default only see published material
- See FlaggedRevs extension --ccornell 11:57, 8 November 2009 (UTC)
the wiki needs clear entry points and from there a clear and consistent navigation and search
end users should by default only see documents from their desired language(s) (defaulting to english if a document is not translated)
- I'm not sure how this could be done unless we rolled out a new DocWiki with full support for language namespaces. This is something we will need to research a bit. --ccornell 11:57, 8 November 2009 (UTC)
Searches, indexes, categories and so on (may be called user space) should reflect constraints mentioned above
FAQs, HowTos, tutorials and the like should clearly indicate for which OpenOffice.org versions(s) they are valid. Older help pages should go into an archive.

Process

Ideas for improving the documentation process.

Category:Documentation/Incoming

Maybe we should have a category "Documentation/Incoming" or "Documentation/Handover" for pages containing "rough" user documentation by the development projects (e.g. Writer). Those could be polished, cleared of duplicate info and integrated in the "Guides" by the Documentation project. The page Writer/page styles is an example of such a page. I guess most of its content is already in the "Guides", but it should be checked if there is any additional info in it. If not or if all content has been merged into the pages handled by the Documentation project, those pages should be deleted. On a second thought it might be a good idea in general to have "${PROJECT}/Incoming" categories for all projects. Everyone would be able to put stuff in these categories saying "I think this belongs to you". Project members then can either:

Integrate the content into their current structure
Move the content to another, more fitting "${PROJECT}/Incoming"

Documentation Ownership on the Wiki

Use Categories to attribute documentation ownership/maintainers. Non-english content should always be attributed to a NLC Project by Categories.

Other

Other ideas? Questions? Comments? (but no critics, please :-) )

Review internal documents?

Some OO.o internal documents, especially specifications, are available, and even sent out, to users. Might some of the authors be interested in our help, with reviewing and polishing (I'm thinking of proof-reading and light copy-editing, mostly)? --TJ 12:46, 5 November 2009 (UTC)

Image naming convention in the wiki?

I wonder if it would be a good idea to give images (resp. screenshots) "speaking" names - e.g. "InsertImageFromFile-icon.png" (or IconInsertImageFromFile.png") as this could reduce redundancy + number of uploaded files and could be also of use if an icon changes. -nino 22:33, 10 November 2009 (UTC)

That's a good idea, and one that has been attempted in a few places. There has been no clear statement on this, so people (myself included) picked image names that made sense at the time (or just used the legacy name from the source docs). --ccornell 07:18, 11 November 2009 (UTC)
Another related question, regardless of naming convention, how do we find out what image have been uploaded? MediaWiki has an image gallery, but it's a generic one showing all images uploaded, not just the ones we want/need. Maybe there is an extension that allows us to view images by Category? --ccornell 07:25, 11 November 2009 (UTC)

Just some additional thoughts

What do we know about our users (in case of documentation - are they called readers?)? Who does need what kind of documentation? Who is satisfied who is not? How could we monitor this 'customer satisfaction'?
- We have access to some visitor stats (although there is a gap of a couple months in the stats due to an error on my part). This might give us some ideas... --ccornell 07:24, 11 November 2009 (UTC)
Would it help to define a (small) set of "top ten" or "most needed documents" on which (updating/translating) efforts should focussed to keep them up to date first (and only later writing all the other stuff) - i.e. the question if priorization would help?
- How do we identify the top 10/most needed docs? By access stats on the websites? This is a question I've been struggling with... We can def prioritize based on our own perception of what is needed, and then fine tune it later based on what data we can collect... mailing list questions and forum posts are a good indicator or where the weak points are (although a huge percentage of the new user questions are answered by them simply pressing F1 and looking in the Application Help). --ccornell 07:24, 11 November 2009 (UTC)
How could we organize users/customers to cooperate creating good documentation? By expressing their needs?
- Maybe a new/different feedback channel? There is a sense of disconnect between the end user and the Doc Project (at least to me). End users/readers don't know what channels they can use to communicate back to the writers... yes there is Issue Tracker, but try explaining that tool to someone who has trouble installing OOo in Windows. The mailing lists seem to confuse a significant number of users as well. --ccornell 07:24, 11 November 2009 (UTC)

Questions

Wiki/OOoAuthors: Do we need to aggree (now) on a single common tool/approach? Couldn't we continue with two (or more) (equal?) tools for a while? And let "the community" decide? For doc localization efforts, it appears many language communities have already made the decision in favour of the wiki, and some (like the German) in favor of the ODT/OOoAuthors.
- I don't think there needs to be a single tool, but what would be nice is a more unified approach to docs, or at the very least a better defined approach (this is especially important for new contributors... a group that we need to build up). --ccornell 07:14, 11 November 2009 (UTC)