An Open-Source, Technical-Writing Collaboration Effort
8 min read
Table of contents
- How does this help people contribute to open-source?
- How does this help people learn technical writing?
- Benefits & Learning Opportunities
- Tech Stack
- Use of Planetscale
- Future Plans
- Important Links
A couple of months ago I launched The Self-Taught Tech Network.
A community focused on helping self-taught developers of all levels feel supported, ask for advice and find their place in tech.
Through this, I have had a lot of discussions with aspiring developers. The most prominent way, outside of reading tutorials to cement your coding skills is by building actual projects.
One of the main issues I heard when speaking to developers was that they lacked inspiration when thinking of a project to create.
This is where the initial idea for the Project-O-Matic came to mind.
Enter your skill level, language and framework, and then like magic (Which is all coding really is) outcomes your next project idea!
I didn't want it to stop there.
I didn't want just the finite number of projects that I can think up to be the only options.
That's when it occurred to me... the other things that these developers of the future mentioned, how do they contribute to open-source, and how do they get into technical writing.
How does this help people contribute to open-source?
Contributing to open-source is well-known to help developers is several ways.
- It strengthens resumes, adding real projects that you can discuss in interviews.
- Improves coding ability, as it allows you to practice your skills, as well as adhere to someone else coding standards.
- Gives experience akin to working in a development environment, as you have to read and understand someone else's code, as well as opening you up to feedback when your code is reviewed.
As much as it has many positives, contributing to open-source can be a daunting task for anyone who is new to it, especially someone who is just getting to grips with the coding fundamentals. Alongside finding projects to contribute to, it can be an intimidating experience opening yourself up to scrutiny, as well as learning the ins and outs of how GitHub works. This is where the project-o-matic open-source collaboration effort can help.
It is a welcoming project for developers of all levels. Offering the chance to get to grips with the GitHub UI/process as well as make their first open-source contribution. Projects are loaded via local markdown files added to the app and solutions are added via a JSON file. These are the ways you can make your first contributions. If you want to find out more, or steps on how to contribute, head over to the GitHub page.
Read below on how you can improve your technical writing using Hashnode.
How does this help people learn technical writing?
The best way to improve your coding knowledge is to build projects. The second best way is to share what you have learnt. This can benefit you as a developer in a variety of ways.
- It forces you to reflect on what you have learnt and explain the concepts in a way that will be understandable to the reader.
- Sharing what you have learnt in places like Hashnode can help to build your social following, build your network and open you up to more potential opportunities.
- It can be a fun respite from coding to switch things up and express yourself in writing.
Your approach to projects can be shared with others looking for inspiration in the form of solutions. A solution is a blog post created in Hashnode. Going into detail about how you created a project in your chosen language and framework.
All you have to do is add the post link and your account to the Project-o-matic GitHub project. Then using their API we can pull in the data when a user requests inspiration. It gets more eyes on what you have written and is attributed to your social media account should people want to know more about you. This can be a write-up you have created especially for this project or one you have created in the past.
For more details on how you can contribute to open-source and improve your technical writing check out the project on GitHub
Benefits & Learning Opportunities
As I mentioned above, this project generator can be a place for developers to come to find inspiration for what to build. Never again will they be sat with an open IDE imagining all they can build is just another To-Do List app...
...that is one of the initial projects though... how could I resist?
Contribute to Open-source
Contributing to open-source is beneficial for a lot of reasons. In my opinion, it opens developers up to working in actual code bases, meaning they have to understand other developers' code, as well as having them adapt to the coding conventions the project owners have in place.
As well as this, having worked on projects that are live can be beneficial to elevating resumes, and giving them actual project experience to discuss with potential employers.
By adding projects and solutions to the project, developers will have a place to share and improve their technical writing skills.
The next best thing outside of creating the project to cement your learning is to teach others. By going over the steps it has taken to make it, developers will cement their knowledge and have to find a way to express their understanding of coding concepts by finding the right way to teach it to someone else.
- Project inspiration generator based on a variety of metrics
- Introduction to open-source by uploading markdown files
- A job runs which adds any new files to the database
- A random project is selected based on the criteria
- A random solution is selected if one is available
- Blazor Server-Side
- I decided to use Blazor as it's the current framework I'm learning. I have a strong understanding of C#, so I can rely on that without taking on too much, but I have also challenged myself as I'm still getting to grips with the inner workings of Blazor.
- An amazing free Blazor component library. Used the modal component to save me time having to write my own UI and logic to show/hide it.
- Entity Framework Core
- Another new learning opportunity. I have only dabbled slightly in EFC in the past, so I used this as the opportunity to dig in properly, and can safely say, I love it.
- Markup processor for .NET
- HTML & CSS
- The usual, the meat and bones.
- I've used Heroku for hosting a blazor server site previously, so I knew the setup would be easy, so I've used this again.
Use of Planetscale
I used Planetscale for my database needs. I have to say now, that this has been the easiest, most painless experience of setting up a database in my whole 5 years of being a developer.
The database was set up and configured in about 10 minutes. Any changes to the database can be manually done through the built-in console. Don't get me started on the branching mechanism that makes database updates between environments risk-free. Plus the fact it's a tried and tested MySql database which linked up perfectly with Entity Framework Core, so I could do any database changes from within the code.
There were a few.
One of those things - life/work got in the way, as I'm writing this I'm on vacation and it's close to midnight. I didn't get as much chance to work on it as I would have liked (Nothing stopping me from working on this after, and I plan on it).
Solving the right way to allow people to upload projects whilst also having it as them contributing to open source.
I didn't want to create a backend management process as the idea is around open-source contributions, not adding stuff via a UI.
I played around with a few ideas, and then I remembered the Hashnode API is quite extensive. Originally I was going to try to have users tag their posts with a specific tag, which I would then use to search for the solution. Sadly the Hashnode API doesn't allow searching on specific tags. Having the users add their post slug and username to a JSON file was an even better alternative to this as it still allows them to make open-source contributions, as well as being a more performant API call as it is very specific.
Design, my old nemesis.
I'm a backend developer. The front end is not my friend. That doesn't mean I shy away, it just takes me time to get my head around styling things, so that slowed me down a lot!
I'm very proud of what I have produced, even if the more design-savvy may have some negative feedback.
Here is the bit I'm excited about most.
I'm planning on running an event as part of The Self-Taught Tech Network to introduce members to technical writing and open-source.
Part of that will include adding projects and creating their own solutions on Hashnode.
The Project-O-Matic is fed data. The members improve their technical writing and coding abilities, as well as, having an introduction to contributing to open-source.
I plan on adding my own over the next few days in between vacation time.
The next steps include writing more detailed guides on how to contribute to the project, including creating a loom walkthrough. Alongside this, I will be working on a few of the issues I am aware of, including the mobile UI scaling. I am open to anyone else getting involved in fixing these as it is an open-source project. Happy to offer guidance on Twitter if you are new to Blazor as a lot of it is just HTML & CSS.
Thanks to Hashnode and Planetscale for hosting this hackathon.
Thanks for reading 💚
You can find me on Twitter @TechPickleJoel