Hi all,
For the developer documentation there is a start of the developer guide
on the wiki (http://wiki.meego.com/Developer_Guide) it is rather blank being
more of a proposal that a finished product, ideal for community participation.
>
>Foster, Margie wrote:
>> I think there are at least two types of documentation being discussed
>here: that which a developer wants and that for an end user (the
>consumer). The tech writer here at Intel is writing the end user help,
>and that's something we can figure out how to open source after the
>first release. However, developer documentation is wide open, AFAIK. I
>think there is an SDK working group, and that might be the place to
>bring up this collaborative effort.
>
I agree, the developer documentation is part of the developer offering of
Meego. Having good tools and good documentation is essential to the success of
Meego as a platform.
>1. API documentation - should be in the source code (Doxygen, or QDoc,
>or gtk-doc, or JavaDoc, or whatever) - any developer should be able to
>patch this. 90% of this type of documentation will be upstream, and is
>not specific to MeeGo
The Meego source code can be used to generate the API documentation. There
needs to be guidelines on how to document the code in order to make it
consistent (a set of recommended doxygen tags for example). For APIs outside
the scope of Meego, for example OpenGL, we should just link to their
documentation and create a use case/user story around howto use OpenGL inside
Meego.
>
>2. Code samples and "toolbox" type documentation, describing how to
>string together different APIs to accomplish something consequential -
>some of these will be documented in the source code, and some of these
>will be in the form of code samples and tutorials, some will be in the
>wiki. We should try, as we started to do in Maemo with the use-case
>template: http://wiki.maemo.org/Documentation/Use_case_template to
>standardise these & centralise them into a kind of searchable knowledge
>base. Much of this will not be applicable only to MeeGo, so we should
>try and make sure that we're submitting docs like these upstream where
>possible
The use case template in wiki.meego.com is copied from the one at Maemo. I
cannot say how we should submit documents to upstream components as they will
have their own policies and ways of documenting, but we can plan to have these
sections to be easy to edit and more open to the community/developers.
>
>3. Developer guides - platform overview, development environment set-up,
>how to deploy an application, UI guidelines - longer documents aimed at
>application developers, reference documents. Mostly MeeGo specific. This
>is where I see a great need for read-write documentation
>
Agreed.
>4. User documentation - how to use the basic desktop, core applications
>included with MeeGo, and also user documentation for user-developped
>applications (oft neglected!) - we should ensure that everyone can
>contribute here, where possible
>
>If you're only talking about the fourth type, then there probably isn't
>a major issue. The developer guides and tutorials & code samples are
>where it will be trickier to have something that works well.
>
The localization of the developer guides and use cases will be rather tricky.
The API reference documentation will be particularly tricky since it is
embedded in the source code. For the other read-write documentation, it might
be possible to have community participation.
The user documentation is different story. Companies making products based on
Meego will have to create user documentation describing the applications,
desktop functions that are available, so reusing their output would make sense
if it is available.
>Since initial versions of MeeGo will primarily be aimed at developers,
>as I understand it, the middle tier of documentation is the most
>important to the success of the platform (in terms of rapid adoption of
>MeeGo as a developer platform). It's also the area where openness is
>most important.
>
>Cheers,
>Dave.
>
>
>--
>maemo.org docsmaster
>Email: [email protected]
>Jabber: [email protected]
>
>_______________________________________________
>MeeGo-dev mailing list
>[email protected]
>http://lists.meego.com/listinfo/meego-dev
_______________________________________________
MeeGo-dev mailing list
[email protected]
http://lists.meego.com/listinfo/meego-dev
