Google Season of Docs 2022

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Documentation Home
• Official Publications
• Other Resources
• FAQ
• HowTo
• Macros
• Docs Development

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:

• E-Learning Calc : https://wiki.documentfoundation.org/Documentation/GSoDOC/2020#LibreOffice_E-Learning_Calc
  • Transposition of the LibreOffice Calc Guide (Spreadsheet) into online learning class
  • Improvements in video sketches in the lessons
• Calc Function Reference: https://wiki.documentfoundation.org/Documentation/GSoDOC/2020#Calc_Functions_Reference_and_User_Guide
  • Created a full set of wiki pages with extended information on the Calc Functions (spreadsheet functions)
  • Added examples and use cases of the functions
  • Fixed documentation issues not detected in the current LibreOffice Help pages
  • Served as reference for improvements of LibreOffice Help pages

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