DEV Community: Christina Gorton

The Impact of Tech Layoffs: A Personal Story

Christina Gorton — Mon, 04 Dec 2023 13:53:36 +0000

According to Lisa Cron, the writer of Wired for Story, our brains relate more to specific stories than generalizations. Saying, "Over 200,000 tech workers have been laid off", doesn't leave much of an impression.

This series aims to make recent layoffs more relatable and give people a space to share their experiences.

In this interview, I had the privilege of speaking with a design professional. They shared their experiences during recent tech industry layoffs.

To protect their privacy, the interviewee has chosen to remain anonymous.

Introduction:

Christina: Can you introduce yourself and describe the role you had before the layoffs?

Anonymous: I worked as a designer at a big agency, overseeing design and strategy.

Initial Impact:

Christina: Can you describe the moment you found out about the layoffs? What was the news communicated to you and were there any signs or warnings leading up to it?

Anonymous: The news came during a Zoom meeting with one of our leaders and an HR representative. It was brief, with minimal information.

There were vague concerns about finances so folks did feel uncertain - but in retrospect, it seems things were much more dire than we anticipated and they could have let us know. Instead, it was always "things are getting better" - and I see that as a lie.

Professional Impact:

Christina: I can imagine the impact has been significant. Can you elaborate on how the layoff has influenced your professional journey and the hurdles you've encountered in the job market?

Anonymous: The layoff has prompted me to consider leaving my field for good. One challenge I've encountered is not being able to share work details due to NDAs. It makes it hard to prove my value. I've experienced harmful work environments, so I've looked at jobs in various industries. I am exploring a transition to different roles and industries.

In my career, I've been misunderstood, faced challenges, and felt undervalued at times. While there have been frustrating experiences, I am now focused on finding a work environment that aligns better with my values.

Personal Impact:

Christina: Shifting our focus to the personal side of things, could you share how the layoff has resonated with you on a deeper, more personal level?

Anonymous: The experience has been challenging. Realizing the misalignment of values within the company was disheartening. Although I know I am skilled in my field, getting laid off can be tough. It has made me feel unappreciated and unwanted. As an older job seeker, I face anxieties when dealing with ageism and systemic inequalities.

Company Culture:

Christina: Before we explore the broader impacts, could you paint a picture of the company culture before the layoffs and how it influenced the overall work environment?

Anonymous: The culture was somber because they could see us not having clients coming in. Our daily work continued as best as it could but the atmosphere of not knowing which of your teammates would be there the next day meant everyone was stressed out. It felt more like Hunger Games than a stable place to work. There was just a cloud over everything.

I’ve described it to friends and they thought I was describing a plot from Squid Games.

Reflection on Industry Trends:

Christina: Shifting our perspective to the industry at large, what are your thoughts on how the recent layoffs might shape the future of the tech industry?

Anonymous: The tech industry is in a significant transition, both coping economically and with the effects of AI. The industry will likely shrink and may not fully recover. The layoffs will likely make existing employees have to bear more responsibilities.

Support Systems:

Christina: Navigating through challenging times often involves a support system. Can you share the kinds of support you've received from friends, family, or your professional network?

Anonymous: I've found support through professional associations and Slack channels tailored to minorities. Also in affinity groups that align with my experiences. Emotional support plays a crucial role during such a devastating time.

Advice for Others:

Christina: What advice would you give to others fearing layoffs in the tech industry?

Anonymous: Trust your instincts and take proactive steps if you sense potential layoffs. Emphasizing value and building internal networks is valuable. But it's also crucial to develop a plan to start interviewing as soon as concerns arise, gradually increasing your efforts.

Reflecting on this experience, it underscores the importance of advocating for more employee protections like:

unions
enhanced employee support structures
a reevaluation of legislation such as At-Will employment

Currently, laws lean more toward protecting companies than the workforce. These changes would contribute to a more supportive and equitable work environment.

Future Outlook:

Christina: Looking ahead, how do you currently envision your future within the tech industry given the recent challenges you've faced?

Anonymous: I don't see a future in tech after this experience. I'm exploring non-profits, teaching, and going back to school. I have been engaging in interviews researching alternative careers. I am stepping away from a field I once loved because I am frustrated with the toxic cultures.

It's sad to see a landscape where hard work, training, and education can be overshadowed by toxic people. These people contribute to an environment that sometimes values aggression more than collaboration. I am using my frustration to motivate me to find a job that matches my values and promotes a better work environment.

Christina: As we wrap up, is there any additional insight or perspective you'd like to share about your journey or the wider implications of layoffs in the tech sector?

Anonymous: Over the next few months, I want to do three things. First, I want to find volunteer opportunities. Second, I want to read more to improve my professional skills. And finally, I want to find companies that appreciate their employees.

I have a few hobbies I want to develop. It will keep me motivated during the job hunt. Employers assume we all have Etsy stores in our spare time!

Christina: What is your ideal next role?

Anonymous: For my ideal next role, I want to focus on finding a position where I can work with respectful coworkers. I want a job that aligns with my skills and doesn't cause stress or discomfort that could lead to PTSD. My mental well-being is a top priority.

Closing Thoughts:

Christina: Is there anything else you'd like to share about your experience or the broader impact of layoffs in the tech industry?

Anonymous: Advocate for humane layoff approaches. Layoffs are inevitable. But it's essential to deliver tough messages with empathy. Those involved in layoffs should undergo communications training.

Leadership should convey a simple, compassionate message:
"This is challenging, but today, we have to lay you off. We recognize this is traumatic. The team values your remarkable contributions, such as your work on 'Name of Product.' You have a bright future, and we appreciate your hard work across projects. Thank you for being part of the Company; we believe any company will be lucky to have you."

This isn't complicated but is crucial. Without improved layoff practices, companies risk being undesirable workplaces.

Christina: What message would you like to convey to your former colleagues or those facing similar situations?

Anonymous: You'll understand how brutal a layoff can be when it happens to you. I hope you'll be ready.

Conclusion

This interview focuses on the impact of tech layoffs with an emphasis on workplace dynamics and employee well-being. We need to work together to make positive changes and create work environments that focus on empathy, respect, and open communication.

If you've experienced a tech transition or a layoff and have a story to share, you can be part of the "Tech Transitions: Navigating Layoffs, Sharing Stories" blog series.

If you're interested in being part of this series, please comment below or send me a direct message.

Your voice is important, and together, we can bring a human touch to the broader narrative of tech industry transitions.

Building Thriving Communities: Strategies for New Community Managers

Christina Gorton — Wed, 29 Nov 2023 18:44:02 +0000

Introduction:

Embarking on the journey of community management in spaces like open-source communities or platforms like Discord or Discourse brings unique challenges and opportunities. Often, community management is seen as synonymous with social media management.

While both fields involve engaging with audiences, community management in these spaces requires a nuanced approach. In this blog post, we'll explore the distinct dynamics of community management, offering the top 10 tips for new community managers to thrive in online environments.

Tip #1: Establish Clear Guidelines:

Lay the foundation for a healthy community by creating clear and concise guidelines. Clearly communicate the expectations for behavior, contribution, and collaboration within the community. This not only sets the tone but also helps in managing expectations and avoiding conflicts.

Examples of communities with clear guidelines are:

Salesforce Trailblazer Community:

Guidelines Overview:
Salesforce's Trailblazer Community provides a comprehensive set of guidelines for community members. These guidelines emphasize the values of respect, collaboration, and inclusivity.

Key Points:

Be Respectful: Members are encouraged to treat each other with respect, acknowledge diverse perspectives, and maintain a positive tone in discussions.
Collaborate and Share Knowledge: The community emphasizes the importance of collaboration and knowledge-sharing to help members grow and succeed in their Salesforce journey.
Adhere to Community Principles: Salesforce outlines specific principles that include refraining from spam, avoiding inappropriate content, and respecting intellectual property rights.

Link: SalesForce Success Guidelines

GitHub Community:

Guidelines Overview:

GitHub, a platform for collaborative software development, has clear community guidelines to ensure a positive and constructive environment for developers.

Key Points:

Be Inclusive: GitHub encourages an inclusive environment where everyone can contribute and feel welcome. Discrimination or harassment is strictly prohibited.
Respectful Communication: Members are expected to communicate respectfully, fostering a culture of constructive feedback and collaboration.
Follow Contribution Guidelines: GitHub provides specific guidelines for contributing to open-source projects, ensuring a standardized and effective collaborative process.

Link: GitHub Community Guidelines

These examples demonstrate the importance of setting clear expectations for community behavior and interaction. Guidelines help create a positive and collaborative atmosphere, ensuring that community members can engage effectively and respectfully.

Tip #2: Encourage Collaboration:

Foster a collaborative environment by emphasizing the importance of teamwork. In platforms like open-source communities, collaboration is at the core of success. Encourage contributors to work together, share ideas, and actively participate in discussions.  The Open Source Guides: Building Welcoming Communities is a great resource to learn more about creating a space for collaboration.

Tip #3: Facilitate Effective Communication:

Communication is pivotal in online communities. Utilize the communication tools provided by the platform, such as forums or Discord channels, to facilitate open and transparent discussions.

Given the nature of online interactions, where nuances like tone and body language are absent, it's crucial to be mindful of how messages may be perceived.

Strive for clarity and considerate language to avoid misunderstandings. Ensure that important information is easily accessible and well-organized, fostering an environment where members feel comfortable expressing themselves while minimizing the potential for misinterpretation.

Ways to create clear communication in your online communities:

Clearly Defined Channels:

Example: Establish specific channels or forums for different topics or types of discussions. For instance, create separate channels for general discussions, technical support, and off-topic conversations. This helps members find and participate in discussions relevant to their interests.

Regular Announcements:

Example: Implement a routine for making important announcements. Whether it's weekly updates, feature releases, or community highlights, consistent communication keeps members informed about the latest developments and fosters a sense of transparency.

Responsive Moderation:

Example: Ensure that community moderators actively monitor discussions and respond promptly to member inquiries or concerns. Acknowledge contributions, address questions, and guide discussions to maintain a positive and engaging atmosphere.

Regular Q&A Sessions:

Example: Host live question-and-answer sessions with community leaders, experts, or special guests. This provides an opportunity for members to interact in real time, seek advice, and engage in meaningful conversations.

Feedback Loops:

Example: Establish mechanisms for collecting feedback from community members. This can include surveys, polls, or dedicated feedback threads. Use insights gained to make improvements and ensure that the community aligns with the needs and preferences of its members.

Community Guidelines Reinforcement:

Example: Periodically remind members of community guidelines and expectations. For instance, share a weekly "Tip of the Week" highlighting a specific guideline or best practice. Reinforcing guidelines helps maintain a positive and respectful community culture.

Tip #4: Provide Regular Updates:

Keep your community informed about ongoing projects, updates, and changes. Regularly share updates on the community platform, whether it's about upcoming features, bug fixes, or general announcements. This helps in keeping community members engaged and informed.

Creating regular Changelogs is a great way to keep your community up-to-date.  

A Beginner’s Guide to Git — What is a Changelog and How to Generate it

Tip #5: Empower Community Leaders:

Identify and empower community leaders who can assist in moderating and guiding discussions. In open-source communities, this may involve recognizing key contributors. In Discord or Discourse, consider appointing moderators who can help maintain a positive and organized environment.

Tip #6: Facilitate Knowledge Sharing:

Encourage the sharing of knowledge and expertise within the community. Platforms like Discourse are excellent for creating knowledge bases. Foster a culture where community members feel comfortable sharing their experiences, insights, and solutions.

Tip #7: Acknowledge and Reward Contributions:

Recognize and appreciate the contributions of community members. Whether it's code contributions in open-source projects or active participation in discussions, acknowledgment reinforces a sense of community and motivates contributors to continue their engagement.

In your open-source projects, you can use tools like contrib.rocks or Open Collective to generate a contributors list and display an image on your ReadMe.

Tip #8: Host Regular Events or Discussions:

Create opportunities for community members to come together, whether through live discussions, webinars, or virtual meetups. This fosters a sense of belonging and provides a platform for real-time interaction, enhancing the community experience.

Many communities set up “Office Hours” where members can pop in and communicate with leaders in the space.

Tip #9: Address Concerns Promptly:

Actively monitor discussions and address concerns or conflicts promptly. Open-source communities, in particular, thrive on a positive and constructive atmosphere. Timely intervention can prevent minor issues from escalating and maintain a healthy community dynamic.

Tip #10: Facilitate Onboarding for New Members:

Streamline the onboarding process for new members by providing clear documentation and resources. In open-source projects, this may involve creating contributor guides. In Discord or Discourse communities, ensure that newcomers have access to essential information to ease their integration. Check out Discord’s Community Onboarding guide to see the best way to onboard new members.

Conclusion: 

Managing online communities in platforms such as open-source, Discord, and Discourse can be challenging. However, with the right set of skills and strategies, you'll be able to foster collaboration, facilitate communication, and create a positive and thriving environment.

Alex Biehl: Open Sourcing a Tool to Generate Haskell Server Stubs

Christina Gorton — Mon, 25 Jul 2022 14:37:04 +0000

Scarf Sessions is a new stream where we have conversations with people shaping the landscape in open source and open source sustainability. This post will give a recap of the conversation I had with our guest Alex Biehl

Alex is a software engineer at Scarf who recently open sourced a tool to generate Haskell server stubs called Tie.

For the full interview please see the video posted on our YouTube channel.

Stream Recap

Can you talk more about what programming languages the engineering team at Scarf uses?

Alex: “We use a different mix of languages. Though there are two things that stand out for the main products, which are Haskell for the backend like data processing metrics, pipeline and all. And the other one is of course, JavaScript for the front-end, like the UI of the product.

“Also one of the defining aspects of our infrastructure is that we use something called Nix to assemble all the infrastructure bits. We use it to build out our binaries, build the containers from those binaries, help manage and distribute our artifacts for deployment.”

Can you describe the difference between Haskell and other programming languages?

Alex: “Haskell is known as a functional programming language. One of the legends of Haskell is that if it compiles, it works okay. Which is, of course, not always true, but it's a good approximation for a lot of things.

“And coming from that background our founder, Avi, decided that it would be a good foundation for a product.”

Did you work in open source before joining Scarf?

Alex: “I've always been an active open source contributor. Most of the time in the Haskell ecosystem. I’ve been contributing to a lot of Haskell infrastructure as well.

“I was a maintainer for Haddock. It's the de facto standard documentation tooling for Haskell. And I also contributed to the core build system called Cabal and also contributed a few small patches to GHC itself, as well as, all the ecosystem around it."

Christina: “I'm always interested in how people get started in open source.

"Was it something that you were just using these things, so you decided to contribute to the project?

“Or were you specifically like, “Hey, I want to do something with open source."

“How did you get started?"

Alex: “I think I'm kind of a pragmatist in that regard. I noticed something isn't working and now you have the chance to either, you know, build it yourself or piggyback off what's already there and improve it.

“And the pragmatic choices of course, to not reinvent the wheel and improve what's there and iterate on that. And that's what brought me to open source and what brings me to contributing to open source even to date.“

Where did the idea for Tie come from?

Scarf Redesign

Alex: “At scarf we are in the process of revamping our UI for the product.
And we thought it would be a good time for us to also not only revamp the user interface, but also revamp the underlying parts that serve those UIs. Right now the API is written in a very ad hoc way.

“We had a chance to revamp the API, we looked at what we had and analyzed all the shortcomings and disadvantages that we saw. And we found that defining your API in Haskell itself is prone to the usual developer habits.

“Something that developers do is build out patterns and mechanisms to type out lines of codes. They reduce duplication and they make things. They consolidate things to make it shorter, to make it more correct, to avoid repeating themselves.

“It happens that the API itself gets less and less explicit because it's hidden behind all those structures that we build in order to easily write the API itself.

“That made it very hard for us to actually find out what the API itself is. Like what is the actual route for this particular endpoint? You have to look it up and dig deep in order to find out. And another issue we found is we often ended up with something I call “scope creep”. Sometimes types that are meant for the public API contract of the API make it into the domain and business logic.

“Which means that in the long term you are coupling your API contract, which you want to support for your customers, to the internal logic of your product. And every time you want to make a seemingly internal change to your logic you might accidentally change the public contract as well."

Developing Tie

“This brought me to two realizations. First, we want an explicit human readable API contract, which we can share with our customers.
Second, I wanted to settle it on co-generation. That means I don't want to type out these very boring interface types or contract types myself. I really want a tool to have it generated for me so that I never ever accidentally make a change in the Haskell code that would break the contract. With those goals in mind the most common choice today for these kinds of things is Open API. Open API denotes domain specific language to model web APIs.

“Where Tie comes into play is that it understands Open API. And Tie takes the Open API format and generates Haskell code from it. It does this in such a way that we only have to implement the actual list for the specific routes and don't have to deal with all those serialization logics and peculiarities.“

What did you find hard or unexpected about open sourcing Tie?

Alex: “One of the things that I fell really short on at first was writing good documentation.

I hadn't even created a good example in the repository when I first open sourced the project. It didn’t have a “How to use” section although we were already using it ourselves in production.

“It was born as a weekend project after two or three days of work and we were putting it into production already after that weekend. So I quickly had other support issues I had to work on before I had time for documentation.

Christina: “This is why bigger teams have dedicated people for documentation, I totally understand. And to Alex's credit he very quickly messaged me because I have been an open source community manager in the past and he asked me how do I make a good readme?

“I think that's a really good point though. Often maintainers or someone who really wants to open source a tool they were using and it was helpful for them don't have time for everything else, like the documentation.
‍Do you have any advice for anyone putting anything out?

Alex: “Don’t let the perfect be the enemy of good."

"You should add documentation and all the parts that got lost on the initial phase of the project. But you know, what's more important I think is, getting initial feedback on the project itself.”

What’s in the future for Tie?

Alex: “Tie is not finished. It doesn't support all of Open API’s setup. The standard is vast so this is the call for contribution right here.

“Help us improve it, file issues. We can definitely help and guide any changes and improvements.”

What else are you working on?

Alex: My pet peeve is proper co-generation for contracts for external systems, for example databases. People like to use ORMs and generators.”

Christina: “Can you explain what ORMs are?”

Alex: “Object relational mappings method. Like an active record in Ruby, Django, etc. And I want a tool that takes your migration folder and generates for you the types very similar to what Tie does. I want the tool to generate types that reflect the records, the structure of the tables in the database then also allows you to basically ingest SQL.

And generate small records around that SQL which are typed. So that you can use your SQL to write theories, to define tables, to alter tables and so on, but still have the good old type system to help so that you don't mix up your types”

For more information on Tie please visit our repository and consider contributing to the project to help improve it.

Are you helping to shape the landscape in open source? Interested in joining us on a Scarf Sessions Stream? Email Christina at christina@scarf.sh.

To learn more about Scarf:
Website

To follow Alex:
Twitter
GitHub

To follow Christina:
Twitter

Tanner Linsley: Building Sustainable Open Source Projects

Christina Gorton — Thu, 21 Jul 2022 14:00:26 +0000

Tanner is the Co-founder & VP of UI/UX at Nozzle. He is also the creator and maintainer of the open source projects, TanStack. He has been active in open source for over 5 years contributing to the TypeScript, JavaScript, and React communities. He joined us to explain how he got started in open source and how he has made working in open source sustainable.

For the full interview please see the video posted on our YouTube channel.

Stream Recap

What would you attribute to the growth of TanStack?

Tanner: "React Table and React query. I built React table and people started to like it, which was my initial entry into open source. React Query was a bigger push into a lot more users. It was a very general purpose library for React. So it drew a very large audience. I thought it was pretty great. Apparently other people did too."

How did you promote your open source projects?

Tanner mentioned that he literally just put his work out on Twitter when he was ready to make it open source.
Tanner: “I published it at 10:00 PM. I got on Twitter and I said, Hey, everybody, check this out. You know? That's kind of how I've done a lot of my releases too. I like doing it that way. Like I don't need to make too big of a fuss over it.”

What is React Location?

Tanner: “Location is an alternative router for React that is not React Router, I guess, because there's not a lot of them out there. Remix came out and they had a lot of great asynchronous routing features in Remix. I wanted to bring those into a routing experience and I needed more control over search params to the extent that no other router I've seen has.

"So I built this custom router from the ground up to have really good search param support and control over URLs.”

Getting Started in Open Source

Tanner expressed that he generally creates projects that he needs for his own work and then open sources them for others to use.

Avi: “That makes a lot of sense. I very much resonate with the experience of building tools that you need for yourself or tools that your company needs as a way to build things that are valuable to other people in general. If it's useful to you, it might be useful to others too and that is exactly how I got my first projects that had any kind of traction beyond just me using them. They were tools that I wanted to build as well. “

Avi mentioned that people ask him how to come up with ideas for an open source project or product and he tells them to build something they find useful first.

Tanner: “I think that's kind of the wrong way to approach open source anyway. I’d rather solve a real problem. And do something that's actually gonna move the needle for users or a product then be like, “oh, I wonder what I could build in open source.

"I feel like you kind of come up with half baked ideas and you're probably just innovating to innovate. I don't think there's as much drive and inspiration when you do that.“

Do you have any advice for people looking to open source their projects?

Tanner: “I can only give advice on what works for me and the best way that I can do it is you have to remove yourself from your code. You are not your code

“If people look at your code and think it's crappy or judge it, honestly you should be just as judgey of your own code as they are. But it's not you, it just represents, you know, an attempt at solving a problem and it's always an attempt, right?

“Things are going to get better. I publish things to be open source because I want them to get better. And I know that by pushing them into the open source ecosystem, I get a lot of eyeballs on it. And in a way, outsource a lot of the difficult tasks of problem solving to those who care about it as much as I do.“

“Nothing is ever going to be perfect enough to release into the open source world as a true product. It's not gonna be ready until you release it and get other people interested in it to iterate on it with you. It's a chicken and egg problem, but you definitely have to put forth the effort, get rid of your ego and, and just kinda say here it is, you know?“ - Tanner Linsley

Avi: “Yeah. I very much agree with that. And I think that translates to not just open source. For anything that you're putting out there in the world, the feedback is the good thing. And the sooner you get the thing out there, the sooner you get that feedback and the sooner you can build something actually great.“

Why are you trying to build a sustainable open source project in addition to your start-up?

Tanner: “I don't really feel like I'm trying to build a business around my open source stuff. What I am trying to build though is a sustainable model for those problems and solutions. And no one ever said that money didn't help solve sustainability, right? You get money in the mix, it just helps a lot of things.

"Right now I am able to sponsor a lot of devs that help me out. I definitely want those projects to live on and that's a great way to do it, because I'm just one person.

"So there's some really bright minds that have kind of organically joined TansStack to carry things forward. ‍

Dominik Dorfmeister is one who basically just takes care of react query these days. The next version of React Query that's coming out very soon is basically his brain child.“

“I want to see that happen for more projects even if they're not mine. I want TanStack to be like an open source home, if you will, for great projects where they can come and actually survive and get taken care of.“ - Tanner Linsley

You have been fortunate to have some great sponsors. What have you done to encourage sponsorship?

Tanner: “It's going to sound really simple, but I think companies really like to be seen. People like to be seen for their contributions and I don't know if you've seen my little sponsor bubble pack that I have on tanstack.com but I think it's really cool and I think my sponsors think it's really cool too.

"The bigger your bubble is, the more you're helping out. And in a way, I've tried to sell that almost as like a partnership real estate space.

"You can change your image and you can tell me where you want it to link to and point to. And it's not just on the GitHub repo, but it's on my website. It's on every project page. It's very prominent. It has been a great way to let people feel like they are being seen for their sponsorships.”

How do you handle burnout as a maintainer? Do you have advice for other maintainers?

Tanner: “When I feel like I am burning out I go work on my startup instead. I just ship something for my product. We have real customers at Nozzle so shipping something new there makes you feel really good. You have to find a balance with your hobbies. I think you can burn out on any hobby and open source is just like a hobby.”

For more information on Tanner Linsley and his open source projects be sure to visit tanstack.com. If any of his projects have helped you in the past, consider becoming a sponsor.

Stefano Maffulli: An Exploration on Standards for Open Source Packaging and Distribution

Christina Gorton — Wed, 20 Jul 2022 19:41:19 +0000

Stefano is the Executive Director of the Open Source Initiative(OSI) and a long time advocate of open source. He joined us to discuss standards that should exist around open source packaging and distribution. He also talked more in depth about what the OSI is currently up too.

For the full interview please see the video posted on our YouTube channel.

Stream Recap

How or why did Avi and Stefano first connect?

Stefano reached out to Avi after reading the NewStack article “Where Does Open Source Fit into Russia’s War with Ukraine?”.

The article quoted Avi, who talked about how Scarf was able to leverage its distribution data to uncover who was downloading and using our packages. Scarf noticed the Russian government was downloading some of its packages and moved to block the traffic.
“Scarf will be blocking all package and container downloads originating from Russian Government sources until further notice.”

Stefano was excited to see a tool that maintainers could leverage and feel empowered to stop bad actors using their software.

Stefano: "As maintainer of a project or as a developer of some open source software, you have no ways of limiting the nasty usage of your software. It feels like you have no way to empower, you know, using your powers to say, look, I don't want my software to be used for nefarious purposes.

"And, that's why, you know, while we were having these conversations about whether the open source movement can have a say to help populations that are being attacked by an oppressor. That's how you and I met."

What can open source developers do about bad actors?

Both Avi and Stefano agreed this was a complicated topic. What kind of powers do maintainers have?

Open source software is pervasive but what tools do maintainers have to stop bad actors?

Stefano: "We feel like we must use the tools that we know how to use, which is our licenses and, copyright and contract law."

Stefano also mentioned that the current tools developers rely on are not powerful enough because for example bad actors are not going to obey the law.

Stefano: "On one hand, you enable dissidents with strong encryption. Yyou enable free speech.
On the other hand, you also empower terrorist organization to go, you know, behind the surveillance. So I think a lot of the conversations that I hear about the, role of developers in civil activism is relying on tools that are not really powerful enough in my opinion, like contract law or copyright."

However distribution data is another tool maintainers could use.

“You don’t have to do business with people who you don’t politically or socially agree with. And distribution seems to be one of those areas where we actually can give open source projects and maintainers a bit more leverage over their own work.”- Avi Press

Maintainers can also be creative with how they block the usage of their software. Many maintainers and open source communities stop bad actors by refusing to provide support.

“Open source is about collaboration but you can pick and choose who you collaborate with.” - Stefano Maffulli

How do you see distribution playing a role in any facet of open source?

Avi believes distribution plays a role in every facet of open source.

Avi: "Yeah, I think that distribution plays a role in pretty much every one of these different sections when it comes to things like security. How do we respond to CVEs when we find them? Knowing what organizations rely on a given vulnerable package can make it a lot easier to you know, to do damage control and tell people that they need to upgrade proactively."

"I think when we talk about, “how do we make sure that open source developers are building financially sustainable projects or secure projects?” It really comes down to having the distribution data. And having observability into that can really enable a lot of these opportunities.

"I think distribution touches just about every aspect of this. And we're really just starting to scratch the surface on kind of the various ways, which this can be powerful. And I think the same thing for all the political activism aspects that we were talking about. This just gives you another tool in the tool chain that you can use to, be creative as was said earlier."

What kind of standards, if any, should exist for open source packaging and open source distribution?

Stefano reiterated that the OSI are the stewards of the open source definition. They don’t write it but maintain it for the community. He believes more conversations in terms of the development of standards for distribution should be encouraged amongst stakeholders.

Avi made the point that these conversations are important. For example, many package registries do not require two factor authentication. This means a single person, who has the power to push a new package version to millions of devices overnight, could easily have their password leaked. He reiterated that it is vital for the OSS community to have best practices and standards around these kinds of situations.

What are the latest problems or questions when it comes to licensing, as it pertains to the OSI?

“The one thing that has always been fascinating to me is the impact of new technologies on the open source definition.” - Stefano Maffulli

The OSI is starting to investigate the impact of artificial intelligence on open source. Stefano talks about how AI is a weird blend of software and data that blurs the line between what users own and no longer own when sharing their content.

Stefano proposes questions like:

What kind of licenses should be on top of an application that uses AI?
What is the right of the user and the right of the developers? He reiterates that changes to technology always bring new challenges to existing standards and definitions.

What do you think the next 20 years of open source looks like?

Stefano: “Our role in the next 20 years is to continue educating and advocating the benefits of open source and to continue to build bridges so that these open source communities can continue to evolve and thrive around new challenges.”

Avi agreed collaboration within open source will help us to continue developing processes and systems that keep open source sustainable and secure.

He mentioned that Scarf is now a sponsor of the OSI.

To that end, we encourage others to consider becoming a sponsor or donating as well. Together we can all work to advocate the benefits of open source for the next 20 years and beyond.

Encourage Community with a Good ReadMe

Christina Gorton — Thu, 02 Jun 2022 16:28:53 +0000

Community is important for the health of an open source project. During my time as an open source community manager and developer advocate, I have seen how a project’s ReadMe can help with discoverability and encourage community contributions when they are well written. I have also seen how projects can turn away users when they don’t take the time to create a good ReadMe.

What Makes a Good ReadMe?

When you are looking to promote your open source project and encourage developers to use it there are a few things your ReadMe could include.

Project Name and Description

First, a ReadMe should be succinct. More detailed documentation about your product or project can be moved to a separate page or website. A few things you can add at the beginning of your ReadMe are:

Product name and logo if available
A short description that can include:
- What your application does,
- Why you used the technologies you used
- Some of the challenges you faced and features you hope to implement in the future.

Examples of project’s that do this well are:
Haystack by Deepset AI

Jina by Jina AI

If your ReadMe is long or contains several sections, a Table of Contents(TOC) is helpful.

There are several tools you can use to create a TOC in your GitHub ReadMe.

First, you can manually generate a TOC with Markdown. You can follow the markdown in this cheatsheet.

To automatically generate a TOC, you can use an online tool like the GitHub Wiki TOC generator. I used this tool to create the TOC in Forem’s Selfhost project when I was a developer advocate there.

Their open source project, Forem, is another good example of a project that uses a TOC to help their community navigate the many sections of their ReadMe.

Installation Guide

As mentioned previously, in-depth documentation should be added to a separate page, but most users appreciate a "Quick Start" or installation guide, so they can test the project quickly.
You will want to provide a quick step-by-step description of how to set up and run the development environment.

Fluent-bit is on example of a project that has a quick start section and links out to more detailed build and install instructions.

Grouparoo is another good example of including a quick reference to running their application, but also linking out to a fuller version.

Usage Examples

Usage examples help your community visualize how your project can be implemented and better explains your project’s use cases.

Kestra includes a demo app users can play within their ReadMe.

Httpie includes several different examples of their HTTP client, including a GIF to help visualize.

Contributor Guide

A contributor guide will encourage your community to participate in the health and maintenance of your project.

A contributor guide is useful for both maintainers and contributors. Guidelines support good pull-requests and issues and encourages good communication between contributors and maintainers, which saves everyone a lot of time and hassle.

Add a License

An open source license makes it easier for other people to contribute to your project. Depending on the license, it will also encourage or discourage the free use and distribution of your project. A public project is not free to use, distribute, modify, or contribute back to by default. You need to add a license to explicitly give others the right to do so.

For more information on open source licensing, see the following resources.

Licensing a repository
The Legal Side of Open Source
The Linux Foundation: Open Source Licensing Basics for Software Developers (LFC191)

Nice to Haves

Credit Authors or Contributors

In addition to a contributor guide, a section giving credit to the authors of the project and/or highlighting project contributors shows your appreciation for your community by centering the work they have done.

One example of a project that highlights their contributors with a “Contributors” section is Plausible. They use a tool like contrib.rocks or Open Collective to generate a contributors list and display an image on their ReadMe.

Additional Things to Check

If the project will be open to the public, you should check the Insights tab in your repository to view the Community Standards.

This tab provides a checklist you can follow to your community the best experience with your project. Try to include:

Maintaining an open source project is both exciting and exhausting. A ReadMe isn’t always at the top of mind when a developer or team open sources their code. Yet, taking the time to craft a good ReadMe encourages community and the health of your project. It will also save you time in the future by answering users questions from the start. Not everything in this list is necessary for a ReadMe, but even the addition of a few of these items will make an impact on your project.

A Different Approach to Measuring Open Source Community Health

Christina Gorton — Tue, 31 May 2022 15:15:13 +0000

What is Community Health?

Community is important to the success of open source software. The health of a community can be measured in different ways depending on the stakeholders involved. To understand and grow a community, project founders and maintainers need visibility into various technical, social, and even financial metrics. These metrics are important because they can help projects form data driven decisions. *But what metrics should we be using? *

This post is inspired by several discussions I have seen around the failings of current open source metrics and the tools used to measure them. This post will discuss what metrics we currently use and what I believe we should be using instead.

Current Metrics

On LinkedIn’s publishing platform Pulse, William Tracz wrote about Open Source vanity metrics and the problem with using them to measure a project's success. Tracz lamented they could not currently see a better way to gather valuable data about open source projects.

What are these current metrics?

Like Tracz mentions, many of the metrics open source maintainers and contributors rely on are considered “vanity metrics”. This term does not mean these metrics are not useful but they often do not give a full picture of a communities health.

Examples of vanity metrics in open source are:

Number of GitHub stars
Number of active commits
Number of new and closed issues
Releases

and more.

Often these are metrics founders and maintainers care about as they provide a way to quickly show “success” but may not actually help when it comes to important business outcomes and decisions.

Tools You Can Use to See Metrics

Orbit

Orbit is a tool you can integrate with GitHub to see metics like:

Pull request opened
Pull request merged
Issue opened
Issue comment created

and more.

As an open source community manager I used Orbit to quickly track new comments from contributors and maintainers so I could respond in a timely manner. I also used it to see when community members were no longer active. This helped me reach out and get feedback.

CHAOSS Metrics

CHAOSS is a Linux Foundation project focused on creating analytics and metrics to help define community health.

Common Room

Common Room is a growth platform that focuses on a business’ community. The platform helps companies connect their community engagement, product usage, and customer data through the use of artificial intelligence.

Bitergia

Bitergia is an analytics tool for software development teams, open source program offices, and InnerSource programs. Open source projects can use this tool to improve decision making and reporting by analyzing software development community, activity, and performance of open source projects.

Merico

Merico provides tools to help engineering teams understand and optimize their productivity and code quality.

What Metrics Should We Use?

“Tracking different types of metrics is essential for free and open source communities. Metrics give project insights into specific efforts and help get a feel of the community’s general perception. For that, tools that can pull data from various sources and develop a visualization of this data will help projects make informed decisions.”
Linux.com Editorial Staff, Measuring the Health of Open Source Communities

In the article quoted above and in William Tracz’s article the need for a tool that can pull more valuable data is apparent. But what data should projects be looking at and what tool could they use?

Beyond Vanity Metrics

What if you could see a project’s impact, identify potential customers, and understand/showcase growth without sacrificing your end-user’s privacy?

Scarf Gateway helps you understand how users are interacting with your open-source project at every step of their journey

Instead of answering questions like “how many followers do we have”, Scarf’s data digs deeper in to a project’s community health and answers questions like:

How many new companies tried our OSS this month?
How many unique users did our OSS have this month compared to last month?
Was the spike in downloads we saw last week genuine growth, or a thrashing CI pipeline from an existing user?
Should I actually spend the time to fix the bug for that one Windows user?

We can also have visibility into how OSS software is distributed.
Instead of wondering who is using our software, Scarf’s data answers questions like:

What percent of our user base has adopted our latest patch?
What cloud providers are the most popular with our users?

Scarf can also help uncover community metrics like your projects discoverability, usage, churn, and commercial reliance. Community Managers can use this data to proactively connect with users and grow a healthy and vibrant OSS community.

This data compliments the metrics you can get from tools like Orbit and answers questions like:

What is the geographical breakdown of our user-base?
What percentage of our user-base is corporate usage vs hobby usage?
What time zones should we cater to with our online event planning?

For a project’s documentation it can answer:

What percent of our user-base is on Windows vs Linux vs Mac?
Which section of our docs are users finding most confusing?

A New Way

This type of rich usage data moves beyond the typical vanity metrics the open source community has typically relied on. While those metrics can tell you a lot about a project, they do not give the full picture of a community's health.

With the addition of tools like Scarf Gateway, maintainers now have the power to make more informed decisions. When maintainers have hard data around who, where, and why companies and individuals are using their software they can better prioritize features, patches, releases and more.

Root to Linux: Search Files with Grep

Christina Gorton — Tue, 04 Jan 2022 15:38:13 +0000

Introduction

Grep is a commonly used command in Linux (or Unix) to search through 1 or more files for a pattern or word.

Fun fact: grep is short for Global regular expression print(g/re/p). It was a command used in a simple Unix text editor called ed(pronounced ee dee). It would print all the lines matching a certain pattern.

There are many ways to use the grep command. In this tutorial you will use the grep command to search within files and directories and print file types that contain a certain string and more.

Prerequisites

You can use a Linux shell or any Unix terminal like the one found on MacOS. If you do not have a Linux distro set up, you can use an online command shell to practice these commands. For this tutorial I used the terminal found on MacOS.
Create a directory on your computer called book and add 2 text files named story.txt and poem.txt. We will use these files throughout the tutorial. If you would like to practice the Linux commands to create a directory, files, and add text please see Part 1 and 2 of my Hands-on Commands tutorial.

Inside the story.txt file add this text:
A Cat Haiku
In the morning
You sleep despite my meow
I stand on your face

Inside the poem.txt file add this text:
A Cat Poem
Meow meow meow
Meow meow meow meow
Meow meow

Example:

Searching Within a File

One way to use the grep command is to search for a word in a specific file. In this section you will use the grep command to search for the word cat in the story.txt file.

In your terminal navigate to your book directory with the cd command then type:

grep cat story.txt

Nothing is returned

This command looks in the story.txt file for a pattern that matches cat. You will see in the terminal that it does not return anything. There is a word cat in the story.txt file but it is capitalized.
The grep command is case sensitive. To return the line in the text file that matches the pattern cat you could type:

grep Cat story.txt

Yet, you may not know the case of a pattern you are looking for in a file. To search for a word or pattern that is case insensitive you can use the -i flag. The -i flag is shorthand for --ingnore-case.

grep -i cat story.txt

The output should now return the correct line that contains the pattern.
Output:

A Cat Haiku

Searching Recursively

When you want to search through multiple files or you are unsure what file contains a pattern you can search recursively through a directory with grep and the -r flag. The -r flag is shorthand for --recursive

In this example we will search for the word meow in the book directory.

The command will use grep, the -r flag, the pattern/string you want to search for, and the path of the directory to search in.

In your terminal type:
grep -r "meow" /Users/cmgorton/Desktop/book

Output:

/Users/cmgorton/Desktop/book/poem.txt:Meow meow meow
/Users/cmgorton/Desktop/book/poem.txt:Meow meow meow meow
/Users/cmgorton/Desktop/book/poem.txt:Meow meow
/Users/cmgorton/Desktop/book/story.txt:You sleep despite my meow

You can see that the command returned every line that matched the pattern in both the poem and story text file.

Invert search with `-v` Flag

Before, we used grep to find all the successful matches of a word in a file. You can use the -v flag along with grep to invert the search. The -v flag is shorthand for --invert-match. This means the search will return all non-matching lines in a file the pattern you are searching for.

In this example we will look for all the lines that do not match the word "meow" in the poem.txt file.

While in the book directory type:

grep -v "meow" poem.txt

Output:

A Cat Poem

You can now try to do the same inverted search in the story.txt file and see what the results would be.

Search for Specific File Types

When we searched through the previous files we knew that they contained the word meow. However, if you were unsure which files contained the word you could search for a specific file type with the -l flag.

The -l flag is shorthand for--files-with-matches`. It will search only the names of files containing selected lines. For this example you will search through the file type .txt to see which files contain the word meow.

Note: This command will search through all files in the current working directory.

Navigate to the book directory.
Type:
bash grep -l meow *.txt
Output:
bash poem.txt story.txt

Note: The * in Linux stands for "zero or more characters". In the example it looks for all files with the .txt characters.

Conclusion

In this tutorial you explored a few of the ways to use grep to search through files and directories for a pattern.
There are a lot of other flags you can use with grep. You can also use pipes to pipe the output of a command through grep to filter out information.

To see all of the options you can use with grep type: man grep in your terminal. This will list the General Commands Manual for grep.

If you would like to see some of these commands as visual content, check out my post where I share my GoodNotes.
// Detect dark theme var iframe = document.getElementById('tweet-1475936778792148993-274'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1475936778792148993&theme=dark" }

Twitter Chat: Chapter 6 Recap

Christina Gorton — Mon, 03 Jan 2022 19:54:54 +0000

Cover Photo by Chris J. Davis on Unsplash

We started a book club! Each week we host a Twitter chat on Thursdays to discuss a chapter of Docs for Developers.

On Thursday Dec. 30th we had our 6th Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 6.

This post is a recap of the chat and a place to continue the conversation.

Visual Content

What docs have particularly good examples of visual content?
What do you like about them?

Megan Sullivan pointed to Vue’s documentation and this flow chart in particular as a good example of visual content.

// Detect dark theme var iframe = document.getElementById('tweet-1476736131232256002-246'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476736131232256002&theme=dark" }

Portia mentioned Julia Evan’s programming zines called Wizard Zines. They use visuals to cover a variety of topics like Bash, Networking, and Linux.
// Detect dark theme var iframe = document.getElementById('tweet-1476745050159824897-272'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476745050159824897&theme=dark" }

Dvkr gave a shout out to the comics that are found in React’s new beta documentation. They enjoy how the comics personify React.

Aisha Blake said she liked Plaid’s documentation because of the illustrations that help her visualize the use of their product. They combine the visuals with helpful code examples.

// Detect dark theme var iframe = document.getElementById('tweet-1476737189459464193-437'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476737189459464193&theme=dark" }

What are your favorite visuals for learning new content?

Creating Visuals

What’s your workflow for creating visual content? At what point in the writing process do you add them?
What tools do you use?
Do you have any questions about creating visual content that this group might be able to help weigh in on?

I shared that my workflow changes depending on the content. Sometimes I start with a visual and create content around it. Other times I leave the visuals for the end. I also mentioned I enjoy using Figma and Affinity designer to create visuals that are SVGs. Some of the visuals I create I like to animate and SVGs make this easier to accomplish.
I use Procreate when creating an image.

// Detect dark theme var iframe = document.getElementById('tweet-1476742105406087169-399'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476742105406087169&theme=dark" }

Valeria uses online white boards like Weje to manage multiple projects and visualize their workflow.
// Detect dark theme var iframe = document.getElementById('tweet-1476786555708657665-811'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476786555708657665&theme=dark" }

Aisha and Portia both admitted they have a hard time creating visual content. Aisha likes to commission illustrations when possible. Portia tries to draw something on paper first and then uses tools like Miro.
// Detect dark theme var iframe = document.getElementById('tweet-1476742781930459145-512'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476742781930459145&theme=dark" }
// Detect dark theme var iframe = document.getElementById('tweet-1476748136911671299-590'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476748136911671299&theme=dark" }

Do you have a preferred workflow? What tools do you like to use to create visuals for your documentation?

Favorite Takeaways

What takeaways from this chapter can you apply to your own documentation practice at work?

Any quotes or ideas that resonate with you?

Sarah Rainsberger had two favorite takeaways. First, she liked the message “Simplify to Amplify". Visuals can be really helpful but can also be very distracting.
// Detect dark theme var iframe = document.getElementById('tweet-1476752775316967425-889'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476752775316967425&theme=dark" }
Second, she appreciated the reminder that screenshots aren’t always the best option. They lack text for screen readers. Use in your documentation only when they are the best option.
// Detect dark theme var iframe = document.getElementById('tweet-1476754273933348869-801'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476754273933348869&theme=dark" }

Portia added she would have liked a section in the book that talked about maintaining visuals. A lot of documentation sites struggle with keeping their visuals up-to-date.

// Detect dark theme var iframe = document.getElementById('tweet-1476749810820603904-624'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476749810820603904&theme=dark" }

Join the Conversation 🗣

You can see the full conversation on the DevEdBookClub Twitter account.
// Detect dark theme var iframe = document.getElementById('tweet-1476734912812097540-673'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476734912812097540&theme=dark" }

Add a comment on the Twitter thread or share your thoughts here to continue the conversation.

What did you think about Chapter 6 of Docs for Developers?

Twitter Chat: Chapter 5 Recap

Christina Gorton — Thu, 30 Dec 2021 18:06:36 +0000

Cover Photo by Chris J. Davis on Unsplash

We started a book club! Each week we host a Twitter chat on Thursdays to discuss a chapter of Docs for Developers.

On Thursday Dec. 23rd we had our 5th Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 5.

This post is a recap of the chat and a place to continue the conversation.

Code Samples

What docs or learning platforms have particularly good code samples?
What do you like about them?

Megan Sullivan showed us an example of the Gatsby docs. She liked that the Gatsby docs would include in a code sample the name of the file where the changes should go
// Detect dark theme var iframe = document.getElementById('tweet-1474199823356071937-551'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474199823356071937&theme=dark" }

Sarah Rainsberger shared a link to the GraphQL tutorials on Apollo Odyssey.
She said:
“I love seeing code WRITTEN out, with arrows pointing to stuff bc its what I do to learn”

// Detect dark theme var iframe = document.getElementById('tweet-1474199477107970059-582'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474199477107970059&theme=dark" }

How do you like to learn?

Do you have any favorite learning platforms and if so, why do you like them?

Preferred Workflow

What’s your workflow for creating code samples?
At what point in the writing process do you add them?
What tools do you use?
Do you prefer static or interactive code samples?

Ramón Huidobro shared that they like to prepare code samples along with the structure.
// Detect dark theme var iframe = document.getElementById('tweet-1474387138070425602-858'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474387138070425602&theme=dark" }

Megan and I both agreed it depended on what we were writing. If I write tutorials I like to have a code sample written out before writing.

// Detect dark theme var iframe = document.getElementById('tweet-1474202962486571010-861'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474202962486571010&theme=dark" }
// Detect dark theme var iframe = document.getElementById('tweet-1474202688732602372-901'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474202688732602372&theme=dark" }

Do you have a preferred workflow?

Favorite Takeaways

What takeaways from this chapter can you apply to your own documentation practice at work?

Any quotes or ideas that resonate with you?

dvkr's favorite quote was “It’s better to write looking forward than backward”. When writing code samples we should be sure we are not making it even harder for learners by adding references or examples that need shared perspective to understand.

// Detect dark theme var iframe = document.getElementById('tweet-1474210152219693058-933'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474210152219693058&theme=dark" }

Ramón shared their favorite quote: “Explanations that accompany your samples are as important as the samples themselves”.

// Detect dark theme var iframe = document.getElementById('tweet-1474387872589434881-858'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474387872589434881&theme=dark" }

Join the Conversation 🗣

You can see the full conversation on the DevEdBookClub Twitter account.
// Detect dark theme var iframe = document.getElementById('tweet-1474198195936776192-998'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1474198195936776192&theme=dark" }

Add a comment on the Twitter thread or share your thoughts here to continue the conversation.

What did you think about Chapter 5 of Docs for Developers?

Root to Linux: Hands-on Commands Part 2

Christina Gorton — Fri, 17 Dec 2021 21:03:30 +0000

Introduction

In part 1 of this guide, you will learned some of the basic Linux commands to see your working directory, list directories and files, make new directories, and create text files.

In part 2 of this guide you will learn the commands to move directories, copy files, add content, and delete files.

Prerequisites

You will need a Linux shell to work with to try these commands in this tutorial. If you do not have a Linux distro set up, you can use an online command shell to practice these commands. For this tutorial I used JSLinux.

Making Changes to Your Directories

Look at the directories above.
In part one of this guide you created the top directory hierarchy. When you created the original directories you added the Elliot directory under Pride_prejudice.

Sometimes when you create directories or files you may find that they are in the wrong place and you need to move them. The character Elliot is actually in Jane Austen’s book Persuasion not Pride and Prejudice.

Moving a Directory

Instead of deleting the Elliot directory and creating a new one under Persuasion, you can use the mv command to move the directory. When using the mv command you add the file path you want to move, then the file path you want to it move to.

In the Linux shell type:

mv austen/Pride_prejudice/Elliot/ austen/Persuasion/

This will move the Elliot directory from the Pride_prejudice file path to the Persuasion file path. You can navigate to the Persuasion or Pride_prejudice directory and use the ls command to see that the file was moved.

Copying a File

Look at the image of the directories again. You can see that in the top directory there is no partner text file under the Pride_prejudice directory.

In the bottom directory there is a partner.txt file under Pride_prejudice/Darcy. You could navigate to that directory and use the touch command to create the file.

However, in this section you will use the cp command to copy the partner.txt file that is under the Persuasion/Wentworth directory instead.

Currently these files are empty but if they had a lot of information in them it would be more efficient to copy the file instead of creating a new one with the touch command and adding the information again.

In the Linux shell type the cp command followed by the file path you want to copy and then the file path you want to copy it to.

In this case you will copy the file from Wentworth to Darcy.

Deleting a File

Another important command to know while working in the Linux shell is how to delete a file or directory.

Look at the top and bottom directories again.
In the top directory you can see the partners.txt file under Churchill. This file is under Knightly instead in the bottom directory.

Delete this file by using the rm(remove) command. Be sure to use the correct file path when deleting a file. For this example type:

rm austen/Emma/Churchill/partner.txt

After you delete the file, change directories into Churchill and use the ls command to see if the file was removed. If no files are listed then your file was successfully deleted.

Editing a Text File

So far you have created three empty partner.txt text files. Now you will use the cat command to add text to the files. The cat command is one of the more frequently used commands in Linux. It can be used to create single or multiple files, view the content of those files, concatenate files, and redirect output in terminal or files.

In this guide you will use it to add content to a file and to view the content of the file.

Change directories to austen/Emma/Knightly.

Then type:

cat > partners.txt

You will be able to type content to the shell. Type Mr. Knightly marries Emma into the shell. To exit type Ctrl + d from the keyboard.

To view the content you can use the cat command and file name.

Alternatively, you can use the less command to view content of a text file.
If you use the less command you will need to type q on your keyboard to exit.

For more practice, navigate to the other partner.txt files and add content to them.

In Wentworth/partner.txt add the following content:
Captain Wentworth marries Anne Elliot.

In Darcy/partner.txt add the following content:
Mr. Darcy marries Elizabeth Bennet.

Conclusion

In part 2 of this hands-on guide you learned the following basic commands:

mv to move directories
cp to copy directories or files
rm to delete files (if you want to delete a directory and all of it's contents use the rm command with the -r (recursive) option: rm -r directory_name
cat to edit a text file or view it's content

If you have worked through both of the hands-on guides take the time to go back through all of the commands to reinforce what you have learned.

Root to Linux: Hands-on Commands Part 1

Christina Gorton — Fri, 17 Dec 2021 21:03:21 +0000

Introduction

One of the most intimidating parts of learning Linux is working with the Linux shell. The shell is a command line interpreter and gives a user the ability to execute programs which are also called commands.

In part 1 of this guide, you will learn and use some of the basic Linux commands to see your working directory, list directories and files, make new directories, and create text files.

Prerequisites

Checking Current Directory

In Linux, a directory is a location on your computer that stores files. They are set up in a hierarchical system on your computer.

To see what directory you are currently in you can use the pwd command.

pwd

While using JSLinux you will be in the root directory.

If you are using the Linux shell on your own computer you will likely be in the home directory.

Creating Directories

Now that you know what directory you are in, you can start creating new directories and set up your own hierarchical structure.

In the image below. you will see several directories and files that are set up in a hierachy. These directories are named after the author Jane Austen, some of her books, and a few of the characters in those books.

In this section of the tutorial you will learn the commands to create each directory, change directories and list the directories that have been created.

The first directory you will create is austen.
To create this directory you will use the mkdir command which stands for make directory.
In the Linux shell type:

mkdir austen

Note: If you type Austen it will be different from austen. The Linux shell sees these as two different directories. Be sure to pay attention to your capitalization and any spelling errors while creating directories or files.

To see if the directory was created you can use the ls command.
This command is short for list and will list out any directories or files that are in the current working directory.

In the image below you can see the austen directory is listed along with a few default directories that come with JSLinux.

Creating Directories Under `austen`

Now you can create the next directories in the hierarchy. You will create the Emma, Persuasion, and Pride_prejudice directories.
You can create each directory one at a time with the mkdir command like you did when creating the austen directory.

or you can create several directories at a time like the image below.

Use the mkdir command and separate each directory you would like to create. Here we create the Persuasion and Pride_prejudice directories all at once.

Once you are done creating the directories you can use the cd command, which stands for change directory, to move from the root or home directory to the austen directory.
From there you can use the ls command to list all of your new directories and confirm they were successfully created.

To create the next directories in the hierarchy you will use the same mkdir command. In the image below you will see an example of changing directories to the austen directory and creating the character name directories.

You must add them to the correct file path. For example, Knightly will go under the Emma directory so you will create it by including Emma in the file path like:
mkdir Emma/Knightly

Repeat the same pattern with the other directories that need to be added.

Note: In the Linux shell you can press the tab key on your keyboard after you start a file path to auto-complete it. For example, if you type Pr then hit the tab key it will auto complete to Pride_prejudice for you. This will save time as you create more directories.

Creating a Text File

In the directory hierarchy image you can see that there are two partner.txt files.
.txt stands for a text file. To create text files you use the touch command.

Navigate to the Churchill directory with the cd command.
Then type:

touch partner.txt

Use the ls command to see if you were successful in creating a text file.

Follow the same steps to create a partner.txt file under the Persuasion/Wentworth directory.

Once you have created both text files you should now have all of the directories and files from the first image.

Conclusion

In part 1 of this hands-on guide you learned the following basic commands:

pwd to see your current working directory
ls to list directories and files
mkdir to create a new directory
cd to change directories
touch to create a text file

In part 2 of this hands-on guide you will learn the commands to move a directory, copy a file, delete a file, and edit a file.

Take the time to go back through the commands you just learned before moving on to part 2.