[maemo-community] Proposed reorganization of documentation bug reporting

[From: Jarmo.Tikka at nokia.com]

Hi,

Thanks Dave. 

We discussed this reorganization of Bugzilla componetns in private mail thread and I just copy-paste my latest reply also to this community list.

I somewhat changed links and descriptions for proposed documentation components (my version top posted below).

Create the following products/subcomponents:

* Device User Guides & Help
  * documents delivered together with device or device sales box
* Developer Guides
  * maemo.org wiki http://wiki.maemo.org/Documentation/
  * reviewed version in Maemo Info Center http://library.maemodocs.nokia.com/
* Tutorials
  * maemo.org wiki http://wiki.maemo.org/Documentation/
  * reviewed versions in Maemo Info Center http://library.maemodocs.nokia.com/
* API Documents
  * from sources delivered from maemo.org SDK repositories http://repository.maemo.org/
  * reviewed versions in Maemo Info Center http://library.maemodocs.nokia.com/
* Example Applications
  * from MaemoExamples Garage project http://vcs.maemo.org/svn/maemoexamples/tags/

Cheers,
//Jarmo

> Date: Fri, 12 Mar 2010 17:57:07 +0100
> From: Dave Neary <dneary at maemo.org>
> Subject: Proposed reorganisation of documentation bug reporting
> To: List for community development <maemo-community at maemo.org>
> Message-ID: <4B9A7263.4080206 at maemo.org>
> Content-Type: text/plain; charset=UTF-8
> 
> 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
> 
> 
>