DIPY project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
DIPY
Technical writer:
Areesha Tariq
Project name:
High-level restructuring and end-user focus
Project length:
Standard length (3 months)

Project description

I am a Software Engineer and have expertise in technical writing. I have over 4 years of experience in authoring high-quality software documentation, user guides, manuals, project descriptions. I live in Islamabad, Pakistan (Timezone: UTC + 5). Currently, I am working as an intern in Outreachy which will continue till 18th August. I participated in Google Season of Docs as a Technical Writer in the organization OpenELIS Global. The original documentation was in French, limited, and out-dated, so I created an extensive and updated end-user documentation in English. I got selected in Outreachy in the organization Perl & Raku for round May-August 2020 as a backend developer of Open Food Facts server. Besides back-end development, one of the major tasks of this internship is to create documentation for modules and functions in POD format. I stepped into the world of open-source last year when I contributed in a few open-source projects and later participated in Google Season of Docs. And this year, I got selected in Outreachy that supports diversity in open source and free software. I have a strong grip on Git as my Outreachy project is hosted on GitHub and I have been making regular contributions to Open Food Facts and Mozilla Fenix since March. I am a Linux user for the past 3+ years and have been using terminal commands since then.

The documentation tools and languages that I have used are Sphinx, Read the docs, Markdown. I liked this idea and want to work on it because I have relevant experience and I would love to use my knowledge and skills to contribute to DIPY. I have experience in the field of digital image processing, computer vision, machine learning. It will help me in better understanding neuroimaging and help in creating documentation. I have vast experience in the medical field. I developed a medical website for doctors, patients, laboratories, ambulance drivers. I worked on another system used by doctors, patients, nurses, lab assistants, and researchers. This will help me in creating documentation that will be easier to understand by the audience.

I have gone through the documentation of DIPY and have noted down several flaws in the documentation. There are multiple loopholes in the documentation that I plan to improve. Current State of the Documentation: The documentation lacks a specific structure and design It can be tedious and time-consuming especially for the new users to navigate Users can find it difficult to obtain information from the guide The content of the documentation needs to be improved As a new user, I found it hard to access the user guide and developer guide. Documentation needs to be reshaped in a way that the information required by the user should be easily accessible Documentation lacks consistency

I plan to do the following:

Define a specific structure and template for the documentation Reshape the documentation such that the users can easily navigate and find the required information Produce a roadmap or list of work items for engaging the community in further documentation work Define templates for the user guide and developer guide Define templates for contributing guide Rewrite, restructure and update user guide, development guide and contributing guide (that can help and motivate new users to contribute to the project) Add non-textual images to enhance the textual explanations Improve consistency across the documentation Create documentation for the new command-line interface

User Guide:

For the user guide, I would focus on using simple, plain language to help users understand even the most complex systems. Jargon, acronyms, and other insider info that a new user might not know would be avoided for better user experience. I will also focus on using visual content, including images, annotated screenshots, graphics, and videos, that quickly shows user how the system works. Good documentation needs a hierarchy of headings and subheadings that lets a user know what each section will show them. And that hierarchy should follow a logical flow that helps the user learn to use the system in the most helpful way. One of the main objectives of this project would be to create accessible content. All the documents and guides would adhere to a consistent style. Using consistent fonts and complementary colors across multiple documents is a must. I will make sure that the users have access to more of the organization’s resources on how to be successful with the system.

Developer Guide:

The Developer guide includes extensive guidance and reference materials to aid the developer in creating contributions to the source code of DIPY. It attempts to lay out the various options available to you, so you can use the right approach, depending on what you want to achieve. The development guide needs reshaping and restructuring. I will rewrite the content of the developer guide. Building dependencies, contributing guide, style guide, coding conventions, documentation guide, installing the development environment, debugging, testing guide, and related stuff will be included and made easily accessible to the developers. When eager new contributors rush over to your project to make their first open-source contribution, they rely on the contributing guidelines to be their guiding hand. Thus the guidelines would be easy to read, thorough, and friendly. Contributing guides are helpful documents that communicate how people can contribute to the open-source project. Contributing to the project should be made as easy and as transparent as possible for the users, whether it’s: Submitting a fix Reporting a bug Becoming a maintainer Discussing the current state of the code Proposing new features

TEMPLATE

This is one of the templates that can be used for the contribution guide. It can be modified and sections can be added or removed according to the requirements of the document.

Contributing to DIPY

  • Welcome Note

TOC

Code of Conduct

  • Our Standards
  • Examples of behavior that contributes to creating a positive environment
  • Examples of unacceptable behavior by participants
  • Our Responsibilities
  • Responsibilities of project maintainers
  • Scope

Scope of Code of Conduct

What do I need to know to help?

If you are looking to help with a code contribution our project uses [insert list of programming languages, frameworks, or tools that your project uses]. If you don't feel ready to make a code contribution yet, no problem! You can also check out the documentation issues [link to the docs label or tag on your issue tracker] or the design issues that we have [link to design label or tag on issue tracker if your project tracks design issues]. If you are interested in making a code contribution and would like to learn more about the technologies that we use, check out the list below. Include a bulleted list of resources (tutorials, videos, books) that new contributors can use to learn what users need to know to contribute to the project.

Setting up the development environment

In this section, I will add the installation procedure and dependencies that need to be installed. Install $project by running: install project

  • Source Code: github.com/$project/$project
  • Issue Tracker: github.com/$project/$project/issues

How to Contribute

How to report a bug

  • Before Submitting A Bug Report
  • How Do I Submit A (Good) Bug Report?

How to submit changes

  • Pull request protocols
  • Response from the team
  • Speed of response

How to request an enhancement

  • Before Submitting an enhancement Suggestion
  • How Do I Submit A (Good) Enhancement Suggestion?

Your first code contribution

  • Beginner Issues
  • Help wanted issues #### Pull Request
  • Process of creating pull request
  • Verify that all status checks are passing.

What if the status checks are failing?

  • Writing Tests
  • Test Coverage

Style Guides

  • Git commit messages
  • Standard style

Support

If you are having issues, please let us know. If you need help, you can ask questions on our mailing list located at: project@google-groups.com, IRC chat, or [list any other communication platforms that your project uses].

License

This section will tell about the license of the project.

Time commitment and communication:

I will give 45+ hours a week but in case of any mishap, I will compensate those hours on weekends. During the community bond period, I will discuss communication means and will finalize weekly meetings, means, and time for those meetings with my mentor. I will keep my mentor up to date about my work; will share my work details via email to my mentor. I will prefer TeamViewer for communicating, as it is easy to use with lots of features like share screens etc.