Season of Docs 2020

General mission statement: To generate useful documentation that allows new developers to be productive as quickly as their own skills allow and users to use our software without going to several different places to find how to do even the most basic of the tasks.

Our commitment to technical writers: We will quickly provide any and all assistance you need and point you to the right people. We will trust you to make documentation decisions both in writing and in organization.

To make things as clear as possible we've divided the task in blocks.

Compiling CCExtractor for the first time.

Audience: Developers of all levels.

TaskCurrent StatusWhere we want to goWhat you need to know
1Tutorial: How to compile CCExtractor on Windows using Visual StudioDocumentation does exist, but it's outdated. Also, the procedure itself it's (possibly) more complicated than it should be.This is an onboarding tutorial. It must be possible for a developer with some experience on Visual Studio to build a working binary having only VS itself, your tutorial, and internet access
2Tutorial: How to compile CCExtractor on Windows using GCCDocumentation exists for GCC on Linux, which is a good starting pointThis is an onboarding tutorial. It must be possible for a developer with some experience on GCC to build a working binary having only gcc (the GNU compiler) itself, your tutorial, and internet access
3Tutorial: How to compile CCExtractor on LinuxDocumentation exists, but it's possibly not really well organizedThis is an onboarding tutorial. It must be possible for a developer with some experience compiling linux programs to build a working binary having only your tutorial, and internet access
4Tutorial: How to compile CCExtractor on OSXNothing recent exists. CCExtractor is known to build on OSX, but none of the core developers uses a Mac.This is an onboarding tutorial. It must be possible for a developer with some experience compiling OSX (Mac) programs to build a working binary having only your tutorial, and internet access

Updating CCExtractor dependencies.

CCExtractor has some dependencies to be built. Some of them are "vendored", meaning we just took the source code and integrated it into CCExtractor, which has the advantage that we don't need to deal with those dependencies changing over time if we're happy with whatever version we are using, but it also has the disadvantage that we're stuck with those versions - and some times we do need to update them.

Some are easy to update, and some require a lot of work and/or magic. The documentation is non-existent, and because we do it every N years for some of the dependencies even the person that actually did it last time doesn't remember the details.

We'd like to prepare good documentation here that anyone can follow so the next time we do this it's not so painful.

The external libraries which we don't vendor (i.e. we use the ones found in the system) are a different problem; of course we don't want to update those, but changes in those libraries often break CCExtractor and we need to follow. We also need documentation for this.

The goal is to write a separate guide for each of the dependencies, which currently are:

LibraryURL
Tesseracthttps://tesseract-ocr.github.io/
Leptonicahttp://leptonica.org/
libGPAChttps://gpac.wp.imt.fr/
zlibhttps://zlib.net/
utf8prochttps://juliastrings.github.io/utf8proc/
protobuf-chttps://github.com/protobuf-c/protobuf-c
libpnghttp://www.libpng.org/pub/png/libpng.html
FreeTypehttps://www.freetype.org/
libhashhttp://libhash.sourceforge.net/
nuklearhttps://github.com/Immediate-Mode-UI/Nuklear
libzvbihttp://zapping.sourceforge.net/ZVBI/index.html
ffmpeghttps://ffmpeg.org/

documentation included with CCExtractor

This refers to the documentation that is shipped with CCExtractor, not to online tutorials.

1Rework help screenWhen you run CCExtractor without parameters it dumps a huge list or arguments.The output is too long, disorganized, it has no examples... this started when CCExtractor had 3 possible options, not 60. This needs to be be reorganized.Cooperation abilities. This is needed because you will need to interact a lot with a developer that adjusts the output to what you recommend.
2Organize existing documentationWe currently have a docs folder with various things.Your job is to classify what we have. This means decide what to throw away (no longer relevant), what needs to be updated but can be saved, what need to be rewritten, what needs to be merged...Patience

Website

1ReorganizeThe website is rather disorganized, and there's duplicate information in several pages, as well as shared content (that is sync'ed manually) between the man pages and the websiteDecide what goes where, rewrite pages, delete pages.-

GitHub

1Create a good template for new issuesWe have a boiler plate template that is too long and doesn't allow to quickly see what the issue is aboutWe want to have a simple template and tells the user exactly what to do, that doesn't feel like you are doing taxes, and that has an output that allows to understand at a glance what a problem is.-

Google Summer of Code

1Improve tasks descriptionsWe've been doing our best every year to improve our tasks description, and we think we've done an acceptable job, but there's room for improvementStarting with two of three "classic" tasks (that are really important to us but no student ever picks), come up with a good definition that is accurate, complete, and points to the right resources.-

User documentation

  • Our user tutorials are hopelessly outdated. There's one to process a DVD, and a basic how-to. We need to generate a number of interest use cases.

  • Write scripts for youtube videos. We don't need you to actually produce the videos (but that would be fantastic, of course). The important thing is the script. We can get someone to read it.

Developer documentation

  • Tutorials on how to do a number of things: Write a new decoder, write a new encoder, how to integrate CCExtractor with other tools, compiling...

  • Help us write an official "onboarding" tutorial to help new developers join the team without feeling overwhelmed by our code base.

Sample Platform

Google Summer of Code documentation

  • Our current documentation for past GSoC projects is "free style", and there's definitely a broad range of quality, possibly because of that. While we don't want to limit great writers by enforcing a specific style it's probably a good idea to have some "baseline" so that less gifted writers can deliver a minimum of quality. It's a pity when a good project gets less-than-stellar documentation.

Google Summer of Code Ideas pages

  • We can use help here. Really. We do our best to produce interesting ideas and amazing projects to work on but we seem to be failing on delivery. Given our ideas page for 2020 (some of them will appear in 2021) - how can be reorganize the content so that it's clearer, more interesting...?