This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- The FreeBSD Project
- Technical writer:
- quaffeine
- Project name:
- Create a Wine handbook chapter
- Project length:
- Standard length (3 months)
Project description
As part of this initiative I would produce an in-depth, guide-length chapter of the FreeBSD Handbook related to the installation, usage, and troubleshooting of WINE (www.winehq.org) on FreeBSD. I would aim to spend 4-8 hours each week working on the items below, unless noted otherwise.
*** Community Bonding
If selected I'd spend the Community Bonding period familiarizing myself with the FreeBSD project's documentation processes and infrastructure. I've always been impressed with the cohesive documentation the project has put out, and I'd engage with team members of the project regarding their workflow. I'd also join and browse user-oriented forums to get a sense of what would help FreeBSD users with regards to documentation in general, and help working with WINE on FreeBSD in particular.
I'd spend some time during this period learning the project's documentation toolchain. This will allow me to hit the ground running during the early weeks of the project if I'm selected.
*** Week 1 (9/14-19): Test Installations & Troubleshooting
I'd spend the first week of the Doc Development phase performing a dry run installation of WINE on FreeBSD's current stable version, as well as installing and running a variety of Windows applications ranging from simple utilities to more complex applications. This is an approach I took in a similar article I did on ReactOS for MakeUseOf (https://www.makeuseof.com/tag/reactos-open-source-windows-clone/), only I would use the first week's time to examine a wider selection of programs.
In my experience spending this sort of time up front is useful for identifying (and troubleshooting) general ""gotcha""-types of issues. This way I would be able to have the solutions in hand when it's actually time to write relevant sections, or at least have requests for assistance out to the appropriate channels.
Week's Goal: To have an outline of the installation chapters and necessary details regarding how to fix common installation issues.
*** Week 2 (9/21-25): Documenting the WINE Installation
During Week 2 I would actually draft the section(s) illustrating the installation of WINE via popular methods, including:
- From source using the ports system;
- Via binary packages using core repositories;
- Using available GUI package managers if available, and;
- From alternate repositories such as FreshPorts (and why a user would want to do so).
Important to this section is a discussion of 32- vs. 64-bit and simultaneous installations, to highlight the extra steps running programs of different architectures requires.
Week's Goal: A polished draft version of the section(s) describing the installation of WINE on FreeBSD. This ""polished draft"" should entail nearly final text (pending proofreading and review feedback), and placeholders for screenshots if not the screenshots themselves.
*** Week 3 (9/28-10/2): Running Your First WINE Program on FreeBSD
Once the WINE subsystem is installed, the next section would detail the installation and execution of some initial programs. These would most likely focus on simple, standalone utilities, such as the open source Notepad++. The goal is to allow users to quickly download an application, install it, and see it working with a minimum of fuss.
This section is important to demonstrate to users that some/many Windows applications can actually run on FreeBSD, making it a viable choice for everyday computing.
Week's Goal: The identification of a small number of programs that install cleanly and (largely) work out of the box, and a polished draft version of the section(s) illustrating their installation.
*** Week 4 (10/5-9): WINE Overview & Concepts
The end of the previous section would allude to the need to do some tuning and customization to get certain applications to work on WINE, at which point an introduction to the WINE subsystem is useful to provide context. These section(s) would examine what comes with the WINE system, how it interacts with FreeBSD, and where a user could start looking to further understand the system or troubleshoot issues.
It's important to note that this section wouldn't aim to duplicate existing resources, but rather present an organized overview that links to other (easily digestible) sources for more information.
Week's Goal: A polished draft of the section(s) introducing the WINE subsystem to users.
*** Week 5 (10/12-16): WINE Configuration on FreeBSD
These section(s) would dive further into actual configuration of WINE, beginning with overall modifications/tuning specific to FreeBSD. They would also illustrate the use of $WINEPREFIX folders, which can be used to customize the WINE environment for a particular application. As there are existing resources that explain this concept in depth, this section would only provide a moderately detailed introduction before linking out to them.
Week's Goals: A polished draft of the section(s) detailing where, how, and under what circumstances in-depth WINE configuration is required.
*** Week 6 (10/19-23): WINE GUIs on FreeBSD
To the extent that setting up WINE to run a given program can be a complex and time-consuming exercise, helper tools exist to make this process easier. This section(s) would provide an overview of the installation and usage of some of the options that exist on FreeBSD, including:
- WINECfg
- winetricks
- playonbsd
- others as available
Week's Goal: To provide polished draft sections(s) with instructions on installing and using as many of the most popular GUI WINE helper applications as is feasible.
*** Week 7 (10/26-30): WINE/FreeBSD FAQs (Research)
Some of the most valuable information regarding complex technical applications like WINE can be found in the interaction between users trying to solve particular problems and experts providing answers. It will save users a great deal of time if some of these FAQs, particularly those the are known to affect FreeBSD users, are collected in one place.
These section(s) would aim to do just that, and I'd spend this week just researching the types of issues FreeBSD users commonly have with WINE, as well as hunting down and (to the extent possible) testing the answers. This will give readers of this Handbook chapter a much better chance of quickly resolving a particular issue.
This section(s) would also include a list of resources on where to look for answers it did not provide.
Week's Goal: Polished draft section(s) containing the most common WINE issues, either as experienced by FreeBSD users or in general, and links/notes regarding their solutions. Note that while this week's work has no draft output, it will likely require a larger time investment to find and reconcile common issues as well as track down their solutions. I'd expect to spend closer to 8-10 hours on this research.
*** Week 8 (11/2-6): WINE/FreeBSD FAQs
This week would be spent synthesizing Week 7 research to create the section(s) on FAQs/common troubleshooting issues (linking out to solutions as appropriate).
Week's Goal: A polished draft of the section(s) listing frequently asked questions/frequently experienced problems, and step-by-step instructions to resolve them.
*** Week 9 (11/9-13): Multi-user WINE administration
This section(s) would offer guidance to administrators looking to deploy WINE in a multi-user scenario. It would include not only best practices to share the sub-system itself among multiple users, but also with regard to the Windows applications deployed within WINE.
Week's Goal: A polished draft section(s) detailing guidance and best practices for FreeBSD administrators to deploy WINE and WINE-based applications to multiple users.
*** Week 10 (11/16-20): Appendices, Review Feedback & Administrivia
While I would strive to implement any feedback received from mentors and other reviewers throughout the drafting process, this week would allow time for more extensive re-organization/re-writing if required.
In addition, I would write any administrivia required for this Handbook chapter (front matter, indices, etc.) during this time, as well as assemble WINE-related further reading (e.g. using the Linux version of WINE through binary compatibility, DOSBox for old games/programs, etc.).
Week's Goal: A polished draft of the entire Handbook chapter, inclusive of all other sections.
*** Week 11 (11/23-27): Handbook Chapter Finalization
I would plan to dedicate this second-to-last week to proofreading all text, checking images, and testing the various outputs (HTML, PDF, etc.) as needed. This week will also allow for updates in the event that any of the above software (from FreeBSD itself to WINE or its helpers) upgrades in the time since it's initial writing.
Week's Goal: Final version of Handbook chapter, inclusive of all required updates.
*** Week 12 (11/30-12/5): Project Finalization
On agreement with project mentors, I'd check the Handbook chapter into source control, assemble the project report, and submit the project as complete.