[maemo-community] Proposed reorganisation of documentation bug reporting

[From: Dave Neary]

Hi all,

Currently, I get the impression that there is some confusion on how &
where to report documentation bugs - they're *supposed* to be reported
against the SDK, and there's no obvious place to report them against
"maemo.org website", which is where I've always looked instinctively.

With Andre, Titta & Jarmo, we've come up with this proposal for
modifying the documentation bug reporting workflow.

First, the existing situation:

* General Developer documentation, wiki stuff, etc.
 - Should be reported against "Maemo Official Platform" > "Development
platform"

* API references bug reports
 - Report against the corresponding product/components and set "docs"
keyword
* Printed and Electronic On-Device Documentation
 - Report against "Maemo Official Platform" > "User guide & Help content"


And now, our proposal:

1. Create a top classification named Documentation listed at
https://bugs.maemo.org/enter_bug.cgi


2. Create the following products/subcomponents:

* Device User Guides & Help
 - docs delivered together with device or device sales box
* Developer Guides
  * maemo.org wiki:
http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/
  * Maemo Info Center http://library.maemodocs.nokia.com/fremantle/index.jsp
* Tutorials
  * maemo.org wiki tutorials
  * Maemo Info Center http://library.maemodocs.nokia.com/fremantle/index.jsp
* API docs
  * maemo.org website
http://maemo.org/development/sdks/maemo_5_api_documentation/
  * Maemo Info Center
http://library.maemodocs.nokia.com/fremantle/index.jsp (to be available
in near future)
* Example Applications
  * maemo.org Garage http://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/

Bugs reported against Documentation->API docs should be moved to the
product they're being reported against with the "docs" keyword as we do
now - this will make two potential places to record API bugs, but I
think this is OK.

We should encourage the use of the "URL" field for creation of
documentation bugs, since this will allow us to filter the bugs
afterwards & make sure they get seen by the right person.

Personally, I don't like having 2 API docs subcategories, but since old
API docs will remain where they are, perhaps it makes sense. What makes
the most sense for me is to use the URL field as the differentiator, though.

Can I have some feedback on this proposal, please? Have people avoided
reporting documentation bugs for example for lack of a good place to
report them? Do you think this will be a net positive change?

Cheers,
Dave.


-- 
maemo.org docsmaster
Email: dneary at maemo.org
Jabber: bolsh at jabber.org