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