Jump to content

Google Season of Docs 2022

From The Document Foundation Wiki

Ideas for Documentation technical writing

Better API Documentation

Objective:

Add examples (code snippets) in API pages (idl files).

The Problem:

The LibreOffice API is extracted from the source code (Doxygen) and is shallow in terms of examples for the occasional script programmer. Furthermore, for the occasional script writer, the complexity of the LibreOffice API is daunting at best. The reason is in great part as consequence of the C++ object oriented programming, which is suited for the professional developer rather than the occasional macro writer, looking to solve a spreadsheet or text document handling.

We envision that with a medium to complete set of code snippets, we will address the need of the macro programmer with a quick way to use the API in the right way and with much less trial and error coding.

The Scope

The scope of the project is the LibreOffice API illustration by examples.

  • Understand the API documentation tools generator (Doxygen)
  • Address a set of API objects, properties, constants, methods and services and supply code fragments showing how to use it. Code snippets must be commented.
  • Work with the LibreOffice script community on the subject
  • Be part of the scripting documentation team, in producing scripting documentation for the end user.

Results expected:

Better illustration of API usage, turning API pages more user-friendly for the occasional macro programmer either in Python or Basic.

Measuring Results

  • An initial set of API entries to be addressed will be defined.
  • The measurement of the progress will done by reading the % of the accomplished tasks with respect of the initial set.
  • All results will be visible in the source code of LibreOffice, immediately

Timeline

Proposed Timeline
Dates Action Items
May
  • Set up of LibreOffice build environment
  • Get familiar with Doxygen tool, explore possibilities
  • Configure Doxygen for improvements, if necessary
  • Get ready to run a build and test LibreOffice
June
  • Add examples to 20% of the API
  • commit to the code
July
  • Add examples to 40% of the API
  • commit to the code
August
  • Add examples to 60% of the API
  • commit to the code
September
  • Add examples to 80% of the API
  • commit to the code
October
  • Add examples to 100% of the API
  • commit to the code
  • Wrap up

Budget

Budget Proposal
Budget Item Amount Running Total Notes/Justifications
Technical writer to publish code documentation of the LibreOffice API 6000 6000 Estimated 1000 per month
2 Mentor Stipends 500 7000
5 t-shirts + S&H 100 7100
Travel & Lodging 1500 8600 Project presentation in LibreOffice Conference 2022

Additional Information

LibreOffice participated in Google Seasons of Doc in 2019 and 2020 and it's mentors are fully qualified to provide guidance for the technical writer. LibreOffice also participates actively in the Google Summer of Code since 2011.

In 2019 we produced a guide for LibreOffice Online available at https://nextcloud.documentfoundation.org/s/gRSwD4E7bSCe4w8.

Our mentoring consisted on the following actions

  • Established a weekly online meeting for project follow-up
  • Provided all infrastructure and access to the relevant information for the technical writer
  • Advise on important topics of the contents.
  • Advise on writing style and docuement formatting for the final product

In 2020 we conducted 2 projects:

The experience in the previous Seasons is key to correctly manage and produce the necessary documentation of the LibreOffice API, a much needed documentation for turn the use of the API more accessible to the end user.

Example of code fragment to create for documentation:

https://gerrit.libreoffice.org/c/core/+/123868

From LibreOffice 7.3 on:

https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1frame_1_1XInfobarProvider.html

Notes:

  • No need for translation
  • files to edit are in offapi/ module
  • build and test is done in odk/ module

Skills:

  • Programming 101,
  • Build LibreOffice
  • Gerrit use