This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Electron
- Technical writer:
- Mister Gold
- Project name:
- Electron Tutorial Flow
- Project length:
- Standard length (3 months)
Project description
PROJECT SUMMARY
Electron is one of the most popular tools to build cross-platform desktop apps with JavaScript, HTML, and CSS. A collection of apps built on Electron has almost 900 entries and this list grows continuously. Some of the most popular developer tools like Visual Studio Code, Atom, Postman, Slack, GitKraken are built on Electron.
The popularity of Electron lies in its simple learning curve and low entry threshold - everyone who knows JavaScript, HTML, CSS stack can build their own application. Huge overall growth rates dictate the need for creating tutorials and getting started guides that are easy to grasp and use.
The project’s goal is to bring confidence to application builders who are new to the Electron framework and provide them with a consistent and streamlined experience in developing their own Electron applications from the ground-ups.
Project Issues
The following is a list of the most crucial issues related to Electron tutorials documentation: 1. Unclear starting point and non-intuitive introduction information about application development steps 2. Scattered and redundant information related to application development process 3. Disorganized pieces of “getting started” guide instructions with no single source of truth
PROJECT PROPOSAL
According to the project’s goal, and the issues outlined above, the following is a list of the proposed enhancements: 1. Update the existing guides. To make the first steps smooth and consistent, the following documents should be updated with a gradual switch from simple to more complex: - Developer Environment - Writing Your First Electron App - Adding Features to Your App (create a summary page) - App Packaging and Distribution 2. Restructure the documentation directory. To show new developers of what is essential to getting started and what can be considered as further steps, the docs page should have both visual and contextual division of the steps to make the first application live as fast as possible. Restructuring also includes guidance on the possible next steps. 3. Organize and unify application development documentation. All the features should have a unified set of instructions on how to install/enable it, how to get started quickly, how to work with an app after the first launch, and how to distribute it. 4. Include electron-api-demos repository in the documentation. The electron-api-demos repository contains a set of examples that show how to add features to your Electron application. This information should be included in the Adding Features to Your App guide to be consistent with a single source of truth content strategy. 5. Integrate Electron Fiddle examples into the documentation. This step will make it easier for new developers to see how a particular piece of code works without having to repeat the steps manually. The integration includes writing code samples for the updated tutorials and adding the “Launch in Fiddle” button to code blocks.
TIMELINE
Application Review Period - Get familiar with the community and people to work with. Learn community contribution guides and best practices. Make the first contributions. Community Bonding - Explore the community. Inspect the current state of Electron documentation. Identify weak points. Week 1 - Align with mentors on the project milestones and deliverables Week 2 - Revise Developer Environment and Writing Your First Electron App pages Week 3 - Revise Application Architecture, Adding Features to Your App, App Packaging and distribution pages. Create a summary page with a list of features that can be added to the app Week 4 - Restructure the documentation directory Week 5 - Prepare a template of how electron-api-demos will be integrated into the main documentation Weeks 6 - 7 - Migrate the electron-api-demos repository Week 8 - Prepare a template of how Electron Fiddle will be integrated into the main documentation. Write the first sample. Weeks 9 - 10 - Integrate the Electron Fiddle into the main documentation Week 11 - Finalization of the main documentation structure and pages after migrating the electron-api-demos repository and Electron Fiddle samples Week 12 - Evaluating results
DETAILED BREAKDOWN OF MILESTONES
APPLICATION REVIEW PERIOD The first part of the period will be dedicated to checking community channels and source code and contacting people who are dedicated to the project.
The second part of the period will be devoted to checking the contribution culture in general, examining contribution guides and best practices. This will be the time for first contributions to see how the flow works.
COMMUNITY BONDING
This time will be devoted to a deeper examination of the documentation folder along with its roadmap. Based on that information, it will be possible to identify weak points (e.g. incomplete or missing parts) that can be improved. Create pull requests (where possible) to fill the gaps.
WEEK 1 - WEEK 2
The first week will be devoted to communication with mentors in order to align on the expected milestones and their timely delivery.
The second week will be about revising the Developer Environment and Writing Your First Electron App pages. For the Developer Environment page it will include rewriting general overview and proofreading. For the Writing Your First Electron App page it will include making the page a consistent step-by-step guide with a clear start and end points, removing redundant information (like two similar code blocks under the Electron Development in a Nutshell and Trying this example section).
Deliverables: Revised, easy to follow introduction guides on how to quickstart with Electron applications.
WEEK 3
This week will be dedicated to: 1. improvements of the Application Architecture page. This includes: - rewriting of the existing information in the Main and Renderer Processes section to make it simple and more intuitive to a first time reader - adding visual representation of the architecture, how processes are connected, how they communicate and their core difference. Examples of visuals: One, Two, Three (low quality). 2. unification of information about all features you can add to your Electron application. This includes rewriting the guides so that they will have a unified set of instructions on how to install/enable a feature along with an example of how the feature works. Additionally, a new page (summary) listing all the available to use features will be created. The unified instructions may look as follows: - Overview - Example: - Code sample - Visual example (where possible)
- simplification of the Application Distribution page. This includes: a. merging Application Packaging into the Application Distribution guide b. dividing distribution methods into automatic and manual c. taking electron-forge as an example of automatic distribution d. taking information about asar from the Application Packaging page and describe copying source files and creating asar archive as examples of manual distribution. #### WEEK 4 This week will be dedicated to restructuring the documentation directory. It includes:
1 - dividing the existing guides in at least three categories: a. Quickstart b. Learning the basics c. Advanced steps
The Quickstart category will contain the basic tutorials (installation, configuration, distribution) to create a consistent series of guides that will allow newcomers to quickstart from scratch. Each guide should contain links to previous/next guides in the series.
The structure may look as follows: 1. Prerequisites 2. Install Electron 3. Create a basic application 4. Package/Distribute the application
After completing the Quickstart section, the user will know the basics of how Electron applications work and will have a fully-working distributable Electron application.
The Learning the basics category will contain the guides aimed at strengthening knowledge about Electron and extending the application created in the Quickstart sections. These guides include: - Application Architecture - Adding Features to Your App - Boilerplates and CLIs
The Advanced steps category will contain more advanced guides aimed at configuring and fine-tuning your Electron application: - Testing and Debugging - Accessibility - Security - Updates
2 - reducing the number of documentation pages. The current version of the documentation contains a certain degree of overlapping content and uncategorized instructions. For example: - Installation and Installing Electron within the Writing Your First App - Application Packaging and Packaging Your App into a File within the Application Distribution - Uncategorized instructions in the In Detail and Advanced categories: Suggestion: move the following documents to GitHub and exclude from the main documentation. These documents are specific to Electron development guidelines and the source repository is the first place to look for them: - Developing Electron - Chromium Development - V8 Development - Issues in Electron - Patches in Electron - Pull Requests - Source Code Directory Structure - Testing - Coding Style
The main idea of the reduction is to get rid of an oppressive number of available guides, joining the scattered puzzle pieces of information together and giving newcomers a more structured, easily navigated and user-friendly version of the Electron documentation.
WEEKS 5 - 7
Week 5 will be dedicated to preparing a template (a way) of how electron-api-demos will be integrated into the main documentation. This template may look as follows: 1. In the main documentation, under the “Adding Features to Your App”, create the categories represented in the electron-api-demos 2. By going through each of the categories, transfer the demo examples to the main documentation: - Code samples can be taken either from the source code or from the description of the corresponding feature in the application - Each transferred example should be followed by the associated description - Each child example (for example, Error dialog as a child of the Use system dialogs) should be transferred under its parent
NOTE #1: there are examples that exist both in electron-api-demos and in the main documentation (for example, keyboard shortcuts, drag and drop). In this case, the example from the electron-api-demos should take the priority and the example in the main documentation should be ignored.
NOTE #2: Many examples in the electron-api-demos application have Live Demo preview of the described feature or functionality. This functionality will be ignored until the Electron Fiddle integration on Weeks 9-10.
- Update the page listing all the available to use features (that was created during the Week 3) respecting the new hierarchy of examples.
Week 6 and 7 will be dedicated to transferring electron-api-demos examples to the main documentation according to the template described above. As the final step, the electron-api-demos repository should be deleted or deprecated.
WEEKS 8 - 10
Week 8 will be dedicated to preparing a template (a way) of how Electron Fiddle will be integrated into the main documentation. This initiative has already been launched (check the details in the issue #20442) by Electron guys along with community volunteers but it requires a proper finalization.
To proceed with Fiddle samples, the basic template may look as follows: 1. Choose an example from the main documentation (for example, the quickstart). At this point, the documentation should contain electron-api-demos examples as well; 2. Recreate the example in Electron Fiddle (using either example code or the source code as a starting point); 3. Save the Fiddle locally into a folder; 4. Move the example into /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * The list of completed examples is described under the “List of Demos” section of the issue. 5. Add the “Launch in Fiddle” button as described in the initial comment in the issue #2848.
Weeks 9 and 10 will be dedicated to integrating electron-api-demos examples (that have already been converted into Fiddles) to the main documentation according to the template described above.
WEEK 11
This week will be fully devoted to the finalization of the writing project after successful migration of the electron-api-demos repository and Electron Fiddle samples. This includes: - checking that all the existing code examples have the “Launch in Fiddle” button - checking that all the existing code examples are working properly as Fiddles - checking that the main documentation no longer refers to the electron-api-demos repository
WEEK 12
Finalization of completed work. Acceptance checks.