niedziela, 20 września 2020

GSoD week 1


As the first week of my GSoD project is coming to an end, I'd like to give you a recap of what I've managed to accomplish so far.

I've worked a bit with my original pull request which was part of my GSoD application. I removed some files from it to restrict the scope and right now it is purely focused on adding doxygen groups to files in the common folder. This will greatly improve the structure of the doxygen output.We are still making some decisions there regarding terminology but I'm hoping this can go in pretty soon. You can view the output of that PR here.

Another PR opened right now is for the doxygen build framework. The idea is to put the doxygen build files in the main project repository. This will make it super easy for anyone who commits code into the repository to run a doxygen build on their updated header files, in order to check if the doc output is fine. You won't even need to push the files to do this, the build just runs locally from CLI using a simple doxygen command. Ideally, this kind of check could even become part of the ScummVM CI in distant future, but right now there are too many doxygen errors to even think about it. From my point of view, this PR is not very urgent - I have my local setup which I am using when rebuilding the doc a over and over as I work on the header files. What we commit into the repository needs to properly reviewed and discussed.

As to the main part of my work - according to the timeline, the first two weeks are about setting up the doxygen build and giving it a proper look. This is ongoing in the PR mentioned above. As the discussions there happen, I have started my work on the header files from the common folder, checking the language, doxygen usage and structure, adding missing information etc. I've got the first PR opened for a couple of header files and some more changed locally which will be put in a PR very soon.

The idea right now is to crawl over all of the header files alphatebitally and opening PRs for sets of 5-10 changed files. I don't think it makes sense to wait until I have done my work on all files from the common folder and only then open a pull request. That is 80 files and I don't want a discussion on one of them to block merging of all the other ones. Also, the longer the files remain in a pull request, the higher the risk of some nasty merge conflicts.

In week 2, I will continue my work in the common folder, hopefully reaching system.h within this week. This file is more important than the other ones and will require extra thourough review, and possibly extra support from the community to make sure everything in there is described in the proper way.

poniedziałek, 17 sierpnia 2020

GSoD 2020 kick-off

Hi ScummVM community! 

I'm more than happy to announce that I've been chosen to participate in Google Season of Docs 2020 to work on ScummVM documentation. From now on, you will see me hanging around Github opening PRs as b-gent.

The aim of my project is to improve doxygen-based ScummVM API documentation that can be currently found here. I will be covering the details of my work in the upcoming posts in this blog. The plan still needs to be refined during the community bonding stage. For now, I can refer you to my project description which is now publicly available on the GSoD website.

I've done quite a bit of tech writing in my life so far, with 11 years of experience in various companies, big and small. I've created documentation for cloud applications, data warehouses, fintech solutions, various SDKs, and embedded devices. I've been good friends with markdown, DITA, RST, and (not surprisingly) doxygen. I've also been a teacher of technical documentation courses at some point, aimed at popularizing the profession of a tech writer in my country.

I am truly hoping to put all this experience to good use when working on this project.

On a more personal note, I live in Kraków, Poland. I've got two small kids who are pretty amazing, especially at driving me crazy every day. I like boxing and jumping rope. It really helps to vent all the stress related to work and parenting.

Looking forward to working with you!

GSoD week 1

Hi! As the first week of my GSoD project is coming to an end, I'd like to give you a recap of what I've managed to accomplish so far...