Documentation/Dashboard/Ideastorm

From Apache OpenOffice Wiki
Jump to: navigation, search

Documentation/Dashboard/Ideastorm/Complete

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

For now, things will be staying as they are. We have one OOoWiki and we can work within that structure. <toggledisplay> 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 separated 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)
Björn, what is your suggestion to make the wiki doc usable for the "lowest" intended target group (which is presumably "User" in your nomenclature)? The present mess is simply unusable (I don't talk about techies and project members but of Jo Average).
IMHO the simple and uncomfortable truth is that the present mess needs to be cleaned up. The mess will not magically disappear by splitting in two wikis. Also most docs evolve in a waterfall model-like fashion:
  1. They get spec'ed (by UX and Devs)
  2. Then project progress gets tracked (by devs) and while doing that devs document the implementation details. They do this mostly in the same docs, which is Bad(tm). But to believe splitting wikis would solve that is an illusion, because as Edwards's Law states: You cannot apply a technological solution to a sociological problem.
  3. Pieces of the rough dev-docs get picked up by the documentation project and get distilled in usable end user documentation.
This waterfall would drain, if there are barriers like different wikis inbetween. Also some topics are sitting between all chairs: for example, even the non-techie Users might want to use a bit of Basic, but that is tightly coupled with the API. Where you you put the BASIC Guide? the Administration Guide?
I guess a separated end user documentation would end up just like http://user-faq.openoffice.org/ did.
How does one clean up the mess? Well, the answer is simple and uncomfortable again:
  • Everything needs to be in a category belonging to a project, which is responsible to clean up "their house" (their categories)
  • Everything not in a category belonging to a project get viciously deleted in two months. Sounds scary? Good. It should.
see also User Experience/SOP
--B michaelsen 00:00, 12 November 2009 (UTC)
One of the problems we face in the Wiki in general is a strong resistance to the cleanup - although, simply doing it vs asking if we can do it seems to be working so far :-) There are also historical decisions made that make wiki cleanup kind of messy... for example language namespaces. It would be nice if we could implement this... we could turn namespaces on... but then we'd have to manually move all the pages for different languages into their own namespace.. not impossible. Or.. another example, I'd love to enable FlaggedRevs to allow for change control, but the problem is configuring it so that it does not disrupt the status quo on the dev side. All issues that can be resolved of course.
It's interesting to see both sides of this argument, and can I see the point being made for cleanup vs split. --ccornell 08:07, 12 November 2009 (UTC)
Clayton, Wiki is doing (with or w/o asking does not matter, in most cases w/o works fine as people in general tend to be constructive) :-) (BTW - do you see, why I suggested to "externalize" discussion?)
-nino 18:08, 12 November 2009 (UTC)
Reply to B_michaelsen: The issue I try to address is not to clean up the wiki. For me, the wiki works as is. (If you continue your category cleanup, it will even work better.) The issue I'm trying to address is usability for "low level" documentation consumers, the primary target group of the User Guides. Hopfully you understand what I mean - I'm not a developer ;-)
-nino 18:08, 12 November 2009 (UTC)

</toggledisplay>

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
      • I'm still having any success with this one. I've installed it a couple of times and am always seeing the same results... it installs/runs, but I cannot get it to produce a mindmap based on the OOo Wiki. --ccornell 09:05, 10 December 2009 (UTC)

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

  • In progress... (slow migrations of docs) --ccornell 09:06, 10 December 2009 (UTC)

Mail Notification containing diffs

This is not possible in the default MW config. It may be possible with an extension, but, what extension <toggledisplay> Clicking on the diff links in Wiki change notifications is more or less time consuming as the page needs to be loaded in the browser first. I'd like to see the diffs directly in the Mail Notifications below the text (like e.g. in MoinMoin). The first 100 diff lines would give enough information. Any chance to get this implemented?

Sure, this can be implemented... if I know what needs to be done to do this... I don't think it's an option that can be enabled.. maybe an Extension is needed to do this? If anyone knows how this can be done, let me know. --ccornell 11:50, 17 November 2009 (UTC)
  • I've looked into this and haven't been able to find any way of including diffs in teh emails. So for now.. this is a "WONTFIX" --А. Е. Харламенков (talk) 09:36, 7 July 2018 (UTC) </toggledisplay>

TinyURL would be nice

Page Names in the Documentation section tend to be very long with the effect that they are easily broken e.g. in e-mails.

Instead of using external ShortURL services - what do you think about having a TinyURL extension which generates a shortlink to each page (on demand or when the page is generated). Something like http://wiki.services.oo.o/w/TiNyUrL_1234567 or similar.

It would be fine if the generated TinyURL would not change when the page is moved to a new place.

In my simple imagination, only a simple table is needed which translates the TinyURL to the real Page name and redirects the request towards it. And, of course, the abbreviated URL should be (optionally?) displayed on every page, e.g. in the sidebar or after the title, so that it could be easily copied and pasted.

Unfortunately, I did not find such an extension on mediawiki.org. So it's just an idea or a possible RFE/requirement of the Documentation Project. But maybe somebody stumbles upon a possible solution (or develops an extension ;-) ). -nino 17:29, 19 January 2010 (UTC)

We're already using the "supported" short URL functionality in MediaWiki - this uses Apache rewrite rules to remove the PHP coding from the URL. I've also searched around, and I haven't been able to find any other solutions (eg an extension to do this) to make an even shorter URL. --ccornell 08:27, 31 March 2010 (UTC)

Usage / Usability

  1. Generally, the wiki (or any docuentation CMS) needs clear entry points and from there a clear and consistent navigation and search
  2. several special issue are discussed below

Document Versioning

  • 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.

L10N

  • 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

Targeting / User Roles

End Users

  • should by default only see published material
    • See FlaggedRevs extension --ccornell 11:57, 8 November 2009 (UTC)
  • Searches, indexes, categories and so on (may be called user space) should reflect constraints mentioned above

Common Terminology List

Need to work toward a single style guide to improve consistency in terminology, writing style, etc. between user guides, help, other docs, building on what's already available. This page on text for the user interface may have all or most of what we need. I have not yet read it in detail to see if everything in it fits the user guides. --jeanweber 11 November 2009

I already started with a style guide in the wiki, mainly intended for the How Tos. Unfortunately, it's not so visible as I would like it to be. I think it's a good idea to look into the two guides and find out what is still missing in the wiki style guide.--Mwaller 11:18, 17 November 2009 (UTC)

Tagging

Just thought of free tagging like in social bookmarking sites (very preliminary thoughts, nothing particular - just the question if it might be of help for doc purposes)

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"
Note: Actually there is Category:Documentation/Candidate meeting the description above. Still, we might find having such a category (with a common naming scheme) for each project useful. --B michaelsen 11:24, 12 November 2009 (UTC)

User-friendly and Prioritized "Task List"

(Need a better term, as I do NOT mean the task list generated from IssueTracker.) Especially for the user guides, we need an easy-to-access, easy-to-edit list of which chapters need what type of work: update for version X, check for accuracy, edit for English usage, fill in missing info or screenshots, etc., and WHO is currently working on what. All with an indication of priority: what's most urgent and important. --jeanweber 11 November 2009

Jean, could this Wiki prototype be helpful? -nino 16:12, 12 November 2009 (UTC)

Consolidate Wiki Rules

Merge:

into one global set of rules.

Mostly Done.--B michaelsen 21:07, 28 March 2010 (UTC)

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.

The Licencing Problem

The Licencing problem should be solved generically.

  • When editing a wiki page, there should be an explicit licence aggreement (ATM there you are pointed to OpenOffice.org Wiki:Copyrights and from there to other pages.)
  • What licence shall we use for which purpose?
  • just FYI: When starting to wikify German OOoAuthors stuff (up to now only the wg2) we had a licencing discussion in the dev@de mailing list, which led to the current solution (triple licenced wiki pages to make back porting to OOoAuthors' ODT going smooth)

Other

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

Category cleanup

Categories need to be renamed systematically. This is especially true for the NLC subcategories which are a totally unsystematic mess. Proposal: Native Language Categories should follow the following scheme:

NLC/${ISO 639-1:2002 language code}

The job should be easy to perform with a bot. --B michaelsen 09:59, 11 November 2009 (UTC)

This also points to one of the other issues... the inconsistent subpage naming with the various language groups. It turned out this way because no one at the time really knew where their language specific content should be... so they made a best guess. I'd like to see the content in various languages consolidated under a master parent page that is the ISO language code for that language (for example how the DE, JA, FR etc communities are now set up). This can be done using a bot... but the NLC people from each community need to be involved. --ccornell 13:20, 23 November 2009 (UTC)

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

  1. 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)
  2. 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)
  3. 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.

The Dutch speaking community is also in favour of ODT/OOoAuthors as a workspace. But can anything be done to have OOoAuthors site more quickly accesible? --vpanter 11:35 11 Nov 2009 (UTC)

Did you ask for a better performance of the OOoAuthors site? --Andreasma 15:31, 24 November 2009 (UTC)

  • 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)
Personal tools