User:Claus chr/ToDo/Amarok

From KDE UserBase Wiki

Suggestions

Document structure

1. Every page should have identical title and page name: Suggested structure

  • Introduction
  • Quick Start Guide
    • Getting Started
    • The Amarok Window
    • The Music Collection
    • Playlists
    • The Context View
    • How to deal with problems
    • Glossary
  • The Amarok Window
    • Toolbar
    • Media Sources Pane
    • Context Pane
    • Playlist Pane
  • Configuring Amarok
    • General
    • Collection
    • Playback
    • Notifications
    • Database
    • Plugins
    • Scripts
    • Changing Layouts
  • Organization
    • Collection
    • Cover Manager
    • Tag Editor
    • Transcoding
  • Playlist
    • Saved Playlists
    • Playlist Filtering
    • Queue Manager
    • Dynamic Playlists
    • Automatic Playlist Generator
  • Advanced Features
    • AFT
    • Script Manager
    • Working With Media Devices
  • Various
    • Moodbar
    • Amarok on other Desktops and Operating Systems
    • Troubleshooting and Common Problems
    • FAQ
  • Reference
    • Menu and Command Reference
    • Keybinding Reference
    • Credits and License

Compared with the current UB TOC, the last three chapters have been merged to one Reference chapter - the original chapters are now sections. Only chapters and sections are shown in the TOC (docbook only supports two levels) - it is probably a good idea to do so in the UserBase version, too. The Advanced Features pages are missing from the current UB TOC - are they "production ready"? Also the (very long) configuration page should perhaps be split?

(The page Amarok/Manual/Organization/CollectionScanning is placed below Amarok/Manual/Organization/Collection in the UB TOC. This doesn't seem to pose any problems, though.)

We should rename pages :( At the very least the pages listed here must be renamed. Because of mismatch between page name and page title links in the docbook to these pages don't work properly. Also, Amarok/Manual should probably be renamed Amarok/The Amarok Handbook (linked from Amarok/Manual/Introduction).

We need to go over all pages to ensure that every section, subsection and so on has the proper heading level. Right now a great number of them has too high a level resulting in a docbook TOC with 93 chapters and many sections!

Images

We need guidelines for images: Are there any rules for docbook manuals?

Questions to consider:

Image size: Images ought to be contained within the regular page (at least most of them) but should be large enough to display details clearly.

Image placement: Should we allow images next to text or should images allways be centered between paragraphs?

Text

We need to go through all pages to ensure that they conform to the guidelines with respect to the use of emphasis, bolding and markup tags. Are the guidelines for docbook manuals identical to UserBase guidelines?


Old issues - some solved

On Amarok/QuickStartGuide/GettingStarted:

  • The First Start Dialog: If First Start is its name it should be bolded, otherwise we should use its proper name (bolded) or a descriptive phrase (unbolded, uncapitalized). Also: isn't it really a guide?
  • The blue wolf: (20px)
  • The Amarok wrench icon: or (20px)
  • The merge icon: or (20px)
  • On some pages sections tend to run together. This is caused by long images placed besides short text sections. Solution: place </translate><br style="clear: both;"/><translate> after the troublesome section. This also works with docbook. See Amarok/Manual/AmarokWindow/PlaylistPane

General issues:

  • Images in image titles must go!
  • How does the docbook script sequence the pages - use content page or follow PrevNext links?
    • Neither first, nor the second. API to export pages sequentially could not be found. This makes ToC parsing useless. The list of pages should be created before exporting (manually.)
Retrieved from "https://userbase.kde.org/index.php?title=User:Claus_chr/ToDo/Amarok&oldid=212788"