This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Technical writer:
- Project name:
- Calc Functions Reference and User Guide
- Project length:
- Standard length (3 months)
I can easily devote 30-35 hours a week during the technical writing phase and 10-12 hours in the pre-writing phase to learn any add on the skill needed for the project. I would like to inform you that currently, I am living in my University(in my home country) where I have access to fast internet and any addon resource needed for the project and I’ll continue from my university itself for entire project duration since we are in COVID-19 the situation I don’t see my University starting any time soon and even if it does I would be in my final year where I am supposed to attend classes for only 5-6 hours a week hence it would not affect the project in any way.
LibreOffice Calc has an extensive (+ 500) list of functions in many categories for which the documentation is quite shallow (but nevertheless accurate) in the Help. Calc's built-in Function Wizard also provides the user with summary information about each function's purpose and parameters. A structure has been created on The Document Foundation's wiki to capture more detailed reference information about Calc's functions.
To populate the wiki structure by writing more detailed contents for each of Calc's functions, flagging adherence to the ODFF standard, including illustrations and diagrams were helpful, giving one or two examples to indicate corner cases and exceptions and providing sample/example files.
PROJECT WORK PLAN
I have gone thoroughly with the core idea of the project and we are essentially trying to document working of each function in the functions wizard and along with sufficient examples for each one covering all aspects of the functions and try making documentation as intuitive as possible so that a new user can look up and in a matter of seconds understand how to use it.
I would consider dividing these functions by categories:
• Database: This section deals with functions used with data organized as one row of data for one record. • Date & Time: These spreadsheet functions are used for inserting and editing dates and times. • Financial: This category contains the mathematical finance functions of LibreOffice Calc. • Information: This category contains Information functions. • Logical: This category contains Logical functions. • Mathematical: This category contains the Mathematical functions for Calc. • Array: This category contains the array functions. • Statistical: This category contains Statistics functions. • Spreadsheet: This section contains descriptions of the Spreadsheet functions together with an example. • Text: This section contains descriptions of the Text functions. • Add-in: The following describes and lists some of the available add-in functions.
Each one has around 20-50 functions with few categories having more. Most of them include a shallow description with syntax and one example.
I would like to add more detailed contents for each of Calc's functions, flagging adherence to the ODFF standard, including illustrations and diagrams wherever helpful, giving one or two examples to indicate corner cases and exceptions in form of remarks, and providing sample/example files. Also adding an important section wherever useful. I will consider going around these functions in categorical format, i.e. picking up one and working vertically and then moving to another category during the technical writing period. Besides I would consider getting used to the work environment during the community bonding period to make things easier during the writing phase. In my experience, discovering all the many little ""gotcha!"" moments of documenting these types of applications require a time investment. Planning-wise, at the outset I'd approach the project by running across these 11 categories to work on, of course, some will need more assistance and hence require more time than others but these things can be addressed while working. Since there is some documentation already existing and I am writing on top of it I’ll consider proofreading after each week’s task is done since it is not good to leave it for the last week.
So below is a rough schedule for organizing the project within time limits.
- Week 1:(14 Sept) • Database
- Week 2:(21 Sept) • Date & Time
- Week 3:(28 Sept) • Financial
- Week 4:(05 Oct) • Information
- Week 5:(12 Oct) • Logical
- Week 6:(19 Oct) • Mathematical
- Week 7:(26 Oct) • Array
- Week 8:(2 Nov) • Statistical
- Week 9:(9 Nov) • Spreadsheet
- Week 10:(16 Nov) • Text
- Week 11:(23 Nov) • Add-in
- Week 12:(30 Nov – 5 Dec)(final)
Documenting the work done and experience gained from this project and working on minor things included 2nd pass proof-reading/editing if needed to get the documentation ready for submission.