DEV Community: Valeria writes docs

Digital necromancy: zebras 🦓, ghosts 👻, and the bitter lesson

Valeria writes docs — Wed, 05 Nov 2025 09:41:08 +0000

I recently fell down a particular rabbit hole on LLMs, and I’ve come out convinced they’re not our doom, just our helpful, digital ghosts. In the spirit of Halloween, here’s a fictional conversation featuring Richard Sutton, Andrej Karpathy, and Adam Curtis, who all wandered into the same philosophical graveyard.

Sutton: I see the hyperbole is still inflating every conversation about AI. It’s either boundless optimism or digital doomsday. Both distract from the real issue: LLMs have nothing to do with intelligence. They’re just glorified next token predictors, which is why the whole doomsday panic is as absurd as the hype itself.

Karpathy: I get it, Rich, but you’re missing the magic in the machinery. Think of a baby zebra, it's running in minutes, not after millions of random spasms. That kind of initialization is evolution’s pre-training. What we’re doing with LLMs, feeding them mountains of internet mud, is a fast-forward version of that. A “crappy” evolution, sure, but it gets things started.

Sutton: But your pre-training depends on our knowledge, our finite data. To develop a more intelligent LLM, you need to retrain it all over again using more data. You’re building a statistical Frankenstein stitched together from dead human text. The “Bitter Lesson” is supposed to be about simplicity and scaling, not sentimental necromancy.

Curtis: But that’s precisely what fascinates me. Andrej, you talk about initialization and constraints as though we were resurrecting meaning itself. What you call “pre-training,” I call exhumation ⚰️. These models are ghosts: aggregations of our collective memory, our fears, our awkward confessions, all mashed together and reanimated to talk back to us.

Karpathy: I actually agree. We are summoning ghosts, not intelligent beings. These models are imperfect, disembodied replicas, cubist portraits of cognition. Yet, like airplanes trying to imitate birds, they might evolve into something profoundly useful, even if utterly alien. The question is whether we can ever fine-tune them into something goal-driven, or if they’ll remain spectral echoes, impressive but hollow.

Sutton: And there it is. A ghost that can’t act or learn from experience isn’t intelligent; it’s a recording. True intelligence requires feedback from reality, not just echoes of the past. Until these models can actually learn from experience, they’ll haunt us with yesterday’s data.

Curtis: So it’s settled then. Frontier LLMs aren't the future. They're the past refusing to stay dead 🧟‍♂️

Happy Halloween! 🎃

Top 5 online mentorship platforms for technical writers

Valeria writes docs — Sun, 28 Jul 2024 14:55:21 +0000

This article was originally posted on Hackmamba.

Do you want to take the next step of your technical writing career and step into a managerial role but don’t have the experience? How do you prove to your employer that you have the skills to assume such a role? Those were the same questions John Paz had when working as a senior technical writer for Atlassian. The answer he gave was mentoring others.

I wanted to gain some experience in helping people. But how do I do that? Is that catch-22: How do you demonstrate proficiency in something when it is not your role and you want to grow into it? Mentoring was one of these easy solutions.
— John Paz

As shared in this episode of The Not-Boring Tech Writer, John Paz discovered that mentoring others is a weighty responsibility. However, it's also an opportunity to embark on a transformative journey that can propel your professional development to new heights and build meaningful relationships.

In this article, we recommend online mentoring platforms where you can build mentoring relationships, explore how mentoring can help you reach your career goals, and list the skills you develop as a mentor.

Top 5 online technical mentorship platforms

Here are five technical writing online mentoring platforms we recommend where you can find a mentoring match, connect with colleagues in the field, and forge long-term mentorship relations.

The Good Docs Project

This online technical writing community is dedicated to creating templates for good documentation. It encourages writers to work in teams, thus fostering a mentoring culture. You don't need to be an experienced mentor. You can enhance your expertise through peer learning and structure your one-on-one mentoring around a specific project.

The Good Docs Project offers a unique opportunity to nurture the next generation of technical writers while making an impact on the field.

Hackmamba Creators Community

This vibrant technical writing community brings together passionate creators from diverse backgrounds and countries. As a mentor, you will find a pool of eager technical writer mentees ready to learn and receive career guidance. This rich environment allows you to share your expertise with others, provide valuable career advice to junior writers, and learn from fresh perspectives. It’s the perfect community for those who thrive on cultural exchange and collaborative growth.

Write The Docs

This is probably the largest community of technical writers. Write The Docs holds several conferences and meetups worldwide, providing opportunities for speaking and giving presentations. Whether you prefer virtual guidance or in-person interactions, Write The Docs provides flexibility to match your mentoring style.

WriteTechHub

This thriving community offers a platform for experienced professionals in technical writing to connect with the next generation of technical writers looking for potential mentors. As a mentor, you will have the opportunity to showcase your expertise and build a reputation. Through their challenges and boot camps, you can structure your mentee's learning around a structured curriculum. Joining the WriteTechHub community will refresh your perspective and help you stay at the cutting edge of technical writing.

Tech Writers

This Discord community prides itself on building an environment of continuous learning and collaboration. Its members come from diverse backgrounds and industries, allowing you to expand your professional network. Whether you're looking to share your expertise, reach your career goals, or get hands-on experience mentoring others, Tech Writers offers the perfect platform to achieve your goals while helping others reach theirs.

The perks of wearing the mentor hat

Helping others already has inherent fulfillment and can propel your professional career. Technical writing is no exception. Mentoring a junior writer can strengthen your skill set and leave a lasting impression on your mentee. Here is a list of the benefits of mentoring:

Reinforced knowledge
As you guide your mentee, you revisit concepts with a newfound understanding. They say the best way to identify gaps in your knowledge is to try to teach it to someone else. Mentoring is an opportunity for you to solidify your knowledge and fill in any cracks you identify along the way.

Building a professional network
Your mentee today could be your next collaborator or even your boss tomorrow. They could refer you to your next employer. Mentoring others means forging real connections that can lead to collaborative projects, job opportunities, or a community of peers to whom you can turn for advice and support.

Career development and recognition
When you mentor others, you become known for your professional achievement and for being a leader who uplifts those around you. This reputation can lead to new opportunities as employers and peers value leaders who uplift others. In fact, a Sun Microsystems career progress study found that “mentors are 20% more likely to receive a raise and six times more likely to be promoted to a bigger job”.

Skills you develop as a mentor

As you mentor others, you also sharpen soft skills you can leverage as a technical writer.

Communication and interpersonal skills
As a mentor, you must listen actively to your mentees and understand their struggles. You must also learn to break down complex information into digestible pieces and communicate information clearly.

Leadership and coaching abilities
Mentoring puts you in a leadership position where you are a guide, a cheerleader, and a source of inspiration. You will learn to give constructive feedback that encourages rather than discourages. You will develop the ability to assess your mentee’s skills and set goals that challenge but don’t break them. An amazing mentor is one who inspires!

Subject matter expertise
You will need a continuous learning approach to teach your mentee and dominate the topics you delve into together. This requires understanding the ‘what’, the ‘why’, and the ‘how’-a level of mastery that solidifies your position as an industry expert.

Problem-solving
Your mentee will come to you with problems they can not solve independently. Your job will be to analyze, break down into simpler tasks, and strategize creative solutions. This process of addressing problems from diverse perspectives will sharpen your critical thinking and critical skills.

Time management and organizational skills
Balancing your professional commitments with your mentoring program will require mastering the art of time management, prioritization, and setting realistic goals for yourself and your mentee. As a result, you'll become a more efficient and organized technical writer.

Conclusion

Mentoring is more than just a role - it catalyzes career growth and personal growth. Like in the case of John Paz, it can open the door to new career paths and drive your professional growth. By sharing your knowledge, you reinforce your understanding, cultivate leadership skills, and expand your professional network. But more than that, you become part of a legacy – every writer you mentor will carry a piece of you with them, creating a ripple effect that elevates the entire technical writing field.

If you are ready to share your knowledge, face new challenges, and elevate your career in the process, join Hackmamba’s Creators Community, where you will discover the fulfillment that comes with lighting the path for others on their technical writing journey.

Navigating the Complexities: Challenges and Solutions in Mentoring Tech Writers

Valeria writes docs — Mon, 22 Jul 2024 16:18:44 +0000

I wrote an article about the benefits of mentoring technical writers for Hackmamba. In that article, I didn't discuss the challenges that mentoring can bring. Mentoring others can be rewarding, but it's not always easy. For some people, it comes naturally, while for most of us is a skill we have to develop. So, let's talk about what potential challenges you might encounter when you're not a natural mentor.

In this article, I will present potential challenges and propose ways to overcome them. I will also talk about the qualities of a good mentor, so you can focus on developing them.

Why should you mentor others?

Mentoring junior technical writers offers benefits beyond personal fulfillment:

Reinforces and deepens your own knowledge.
Expands your professional network.
Enhances career advancement prospects.
Improves the likelihood of promotions.

Skills developed through mentoring include:

Enhanced communication and interpersonal abilities.
Leadership and coaching capabilities.
Strengthened subject matter expertise.
Improved problem-solving skills.
Better time management and organizational skills.

Also, mentoring creates lasting connections that can lead to future collaborations and opportunities.

What are the qualities needed to become an effective mentor?

The main challenge of mentoring is fostering an environment that is both challenging and encouraging, so that you and your mentee stay engaged. This is by no means an easy task. You need to break down projects into small, easy-to-tackle tasks. Working on large, complex problems will likely lead to frustration for you and your mentee. Starting with something simple and gradually increasing the complexity is the best way to build confidence.

The mentor-mentee relationship is also about chemistry. Finding a communication style and working relationship that suits both of you can take time, so be patient. Much of this depends on your actively listening to your mentee's pain points. If you don't know what their struggles are, you will never come up with ideas to help them overcome them.

Remember when you were in your mentee's shoes and ask yourself these questions:

What helped you push through?
Who inspired you the most and why?

The answers to these questions can help you inspire your mentee to push through the challenges. Also, remember when you were a beginner and the struggle you went through. Use this experience to deepen your empathy and create an honest human connection. The more you find ways to connect with your mentee, the more you forge a relationship that transcends the mentor-mentee dynamic.

Beyond drawing from your experience, provide constructive feedback that motivates your mentee to keep pushing themselves. Always pointing out someone’s flaws drains their energy. Offer resources that support your mentee’s development and create opportunities for collaborative learning. For example, admit when you don't know something and use it as an opportunity to learn together.

In summary, I believe that these are some of the skills that mentoring requires:

Problem-solving skills
Patience
Active listening
Adaptability
Empathy

Challenges and how to overcome them

As with any other rewarding experience, mentoring comes with its fair share of challenges. Now I want to explore what challenges you might face as a technical writer mentor and discuss potential strategies you could use to overcome them.

The time crunch challenge.

As a technical writer, you are already packed with meetings, deadlines, and writing projects, and the idea of finding time in your busy schedule to allocate to your mentee might overwhelm you.

The solution? Commit to a specific time and frequency for mentoring. After you and your mentee agree on the details, guard this time box fiercely. Or, invite your mentee to shadow you while working on tasks related to your mentee’s task. They’ll learn, and you will get another pair of eyes on your work. It’s a win-win!

The knowledge gap challenge.

Let’s assume your expertise is in Darwin Information Typing Architecture (DITA), but your mentee struggles with Markdown.

How do you bridge this gap? Embrace the role of co-learner. Say, “I don’t know Markdown, but let’s learn together”. This approach keeps you adaptable and fosters a collaborative learning environment that can increase accountability for you and your mentee.

The communication challenge. Everyone has their own way of learning. Perhaps you learn better when you take notes, but your mentee is more visual. Or perhaps there’s a language barrier.

Solution? Use tools like Miro for visual brainstorming and diagramming. Try pair writing sessions with collaborative tools like Google Docs. To overcome language barriers, provide written summaries using simple language.

The imposter syndrome challenge.

You and your mentee might grapple with imposter syndrome. You might doubt your mentoring skills, and your mentee might think they’re not progressing fast enough.

How do you overcome this problem? Keep track of the lessons you have learned together and your achievements, and review them every now and then. Share your struggles with your mentee and how you overcame them: “When I first worked on API docs, I felt completely lost. Here’s how I pushed through…”. Sharing your stories, particularly when they resonate with your mentee, can strengthen your bond.

Conclusion

Mentoring in technical writing is a two-way street that benefits both the mentor and the mentee. As you guide others on their journey, you'll find yourself growing professionally and personally. The skills you develop and refine through mentoring—from communication to leadership—will serve you well throughout your career. Moreover, the connections you forge and the reputation you build as a mentor can open doors to new opportunities. So, whether you're a seasoned technical writer or just a few steps ahead of others, consider taking on the mentor role. It's an investment in your own growth, your mentee's future, and the broader technical writing community. Remember, by lifting others, you ultimately lift yourself.

The Product is Not Docs, But Treat Docs Like a Product

Valeria writes docs — Tue, 30 Apr 2024 03:40:41 +0000

As a software technical writer, I recently finished reading the book "The Product is Docs" by Christopher Gales and the Splunk documentation team. The book offers practical advice on treating your documentation as a product. Initially, I was fully convinced that technical documentation is a product in and of itself. However, after careful consideration, I've changed my perspective.

While researching for a method article about measuring documentation quality for The Good Docs Project, I came across Bob Watson's insightful series on his blog "Docs By Design." Watson presents compelling arguments that documentation is a satellite to the main product or project. This resonated with me because documentation exists primarily to help users when they're stuck. Most people consult documentation to find answers to specific questions, not for leisurely reading. They engage with the docs because they need assistance, not for the sake of reading the documentation itself.

So, no, the product is not docs.

However, this realization doesn't diminish the importance of treating documentation as a product. In fact, I believe it's the best approach to building trust with your users or clients for the following reasons:

Commitment to User Experience: Treating docs as a product demonstrates your commitment to providing users with the best possible experience with your actual product.
Meeting User Expectations: Users and clients expect to find autonomous ways to solve issues and get unstuck when using your product. High-quality documentation meets this expectation.

In summary, while the product itself is not the documentation, treating your docs like a product is crucial. It showcases your dedication to helping users succeed with your product and fosters trust in your commitment to their experience.

So, there it is – my nuanced view on the matter. The product is not docs, but docs should be treated like a product.

Finding the right learning approach

Valeria writes docs — Mon, 15 Apr 2024 22:58:40 +0000

As a coding enthusiast, I've had my fair share of ups and downs when it comes to learning the fundamentals of HTML and CSS. While I had previously completed FreeCodeCamp's Responsive Web Design course, which provided a comprehensive overview of these core web technologies, I found myself feeling lost when attempting to apply this knowledge to solve challenges.

Determined to fill the gaps in my understanding, I stumbled upon a real gem - Kevin Powell's Crash Course on HTML and CSS. As an excellent instructor, Kevin has crafted a well-structured course that strikes the perfect balance between theory and practice. What I particularly appreciated were his suggestions on how to effectively comment on your code and organize your files - crucial skills for any aspiring web developer.

After completing Kevin's course, I felt empowered to tackle my first Frontend Mentor challenge, a QR component. Kevin's teaching method, which uses the analogy of book pages to organize HTML elements, resonated with me. However, I found that I preferred to think in terms of containers. For example, element is the largest container and the rest of the containers are within it. Talking about the QR code component, the

element contains a element representing the white card. Within this white card , I put text and the QR code image.

<!DOCTYPE html>
<html lang="en">
<head>
  <link>
<title> QR component </title>
</head>  
<body>
  <div class="qr-container">        
        <img>
        <h2> </h2>
        <p> </p>
  </div> <!-- / qr-container -->
  <div class="attribution">
    <p> </p>
  </div> <!-- / attribution -->
</body>
</html>

Visualizing the structure of the HTML in this way made it much easier for me to style the component with CSS. This experience taught me a valuable lesson: finding your learning style is key to truly understanding and applying HTML and CSS.

While FreeCodeCamp is undoubtedly one of the most famous learning resources for web development, I discovered that their teaching strategy didn't align with my learning process. I learn best when presented with a combination of theory and practice, followed by the opportunity to apply that knowledge to problems of varying difficulty.

If you're struggling to grasp the fundamentals of HTML and CSS, I encourage you to explore different learning resources and techniques until you find what works best for you. Remember, the path to becoming a skilled web developer is not one-size-fits-all. By embracing your unique learning style, you'll be well on your way to becoming a confident and capable developer.

Do you know what's your learning process?
Share it below so we can compare it with other learning styles.

How concept maps can help create clear and concise technical documentation

Valeria writes docs — Wed, 03 Jan 2024 15:57:18 +0000

A key attribute of good documentation is that it must be clear, concise, and accurate. Technical writers often have to explain intricate systems, processes, or products to readers who may not have deep technical knowledge. This means translating complexity into easily understandable language - no small feat! An invaluable tool that can aid technical writers in overcoming this challenge and creating clear, concise, and accurate documentation is concept maps.

Concept maps are graphical representations that illustrate the relationships between key concepts. They organize information hierarchically, allowing writers to view both the big picture and the granular details. In this article, I’ll explore how incorporating concept maps into the process of creating documentation can enhance clarity, conciseness, and accuracy.

Understanding concept maps

Before talking about the benefits of using concept maps to write technical documentation, we need to understand what are concept maps. Concept maps are rooted in David Ausubel's learning theory which states that meaningful learning requires clear conceptual presentation.

Concept maps consist of concepts and the relationships between them, which form propositions. Each proposition contains two or more concept labels connected by linking relationships. By carefully choosing concepts and linking words, concept maps can effectively capture nuances of meaning. Concepts are typically represented as nouns while linking phrases are represented as verbs. Well-constructed concept maps exhibit propositional coherence, where each pair of concepts and their linking phrase form a meaningful statement.

To construct a concept map, it is important to start with focus questions that require explanation rather than simple descriptions. These questions should promote deep and meaningful thinking. Key concepts specific to the domain should be identified and ranked. A hierarchical organization is then built, with more general concepts at the top and more specific concepts below. By following these steps, learners engage in meaning-making and create well-organized maps that facilitate understanding.

In this manner, concept maps serve as both a learning and evaluation tool, helping writers understand key concepts and test their knowledge of the topic.

In the following sections, I will explain the key features of concept maps and how they can assist technical writers in ensuring documentation is clear and concise.

Organizing knowledge

A key benefit of concept maps is their ability to structure multifaceted information coherently. By visually depicting relationships between concepts, they provide a framework for writers to present content systematically. More general, high-level concepts are shown at the top, with increasing levels of specificity as you go downward.

This organized structure gives both writers and readers an invaluable aid for comprehending complexity. Writers can use it as an outline to build up detailed documentation piece by piece. Readers can reference the map to clarify relationships between components.

You can check out my previous post Basics of Git explained with a concept map, for a demonstration of how you can create a concept map that explains two focus questions and how you can write a document by explaining that concept map.

Structuring complex systems

Technical documentation must often explain intricate systems with interdependent parts. Concept maps explicitly display interconnections through linking phrases, helping break down confusing processes into logical steps.

For example, in the concept map I created to explain the basics of Git I laid out each stage in version control and its ties to other stages. This concept map enabled me to smoothly guide readers through what might seem convoluted procedures.

Enabling collaboration

Because concept maps serve as shared visual models, they can facilitate efficient collaboration when creating documentation. Stakeholders can provide feedback by modifying specific concepts and relations of the map before full prose descriptions have been written. This collaborative approach helps to surface inaccuracies early on, resulting in documentation that precisely conveys the subject matter. In this stage of the writing process, is where concept maps serve as a tool to test the writer's understanding of the product they're documenting.

Conclusion

Leveraging concept maps is a best practice when developing clear, concise, and accurate technical documentation. By organizing complex domains into understandable formats, concept maps can help technical writers distill topics down to their fundamental essence. Embracing this incredibly useful technique will enhance the precision of your technical writing.

How can I learn to write simpler code?

Valeria writes docs — Fri, 22 Dec 2023 01:56:10 +0000

I'm taking Harvard's CS50 Introduction to Python Programming course and I'm shocked by how ugly my code is.

I'm a beginner and assume that everyone goes through this stage where your code is overcomplicated. But how can I speed up my learning curve and write cleaner, simpler code?

When solving coding problems, I always write my own code first and after I'm sure it does what it needs to do, I go to Bard and ask it to improve it. What I've learned from comparing my code to Bard's version is that my algorithms are too complicated.

With all the shame I have, I will present an example.

Ashamed dog

The following code is part of a function that takes a string entered by a user and checks if the string complies with five different conditions. For the sake of simplicity, I will present the code for only one of these conditions. The condition is: the string can't have numbers in the middle and the leading number can't be a zero.

This is the code I wrote to check this condition:

if any(char.isdigit() for char in input_str):  
        for i in range(len(input_str)):
            if input_str[i].isdigit():
                if input_str[i] == '0':
                    break
                else:
                    number_index= i
                    contains_number = input_str[number_index:]
                    if contains_number[0] != 0 and all(char.isdigit() for char in contains_number):
                        condition_met += 1
                        condition_list.append(6)
                break
    else:
        condition_met += 1
        condition_list.append(6)

and this is Bard's version:

digits = "".join(char for char in input_str if char.isdigit())
    if not digits:  
        condition_met += 1
        condition_list.append(5)
    else:
        if digits[0] != '0' and digits == input_str[-len(digits):]:
            condition_met += 1
            condition_list.append(5)

My code has 15 lines and Bard's code has 8. A lot more concise.

So my question for more experienced programmers is, how can I improve my solving-problem thinking?

I am enjoying a lot learning to code precisely because it teaches you to break down problems into small tasks but I'm shocked to realize that my solutions are complicated and that I can do better at making them simpler. How can I learn to create simpler code?

Creating Standout Documentation: The Six C's of Technical Writing Excellence

Valeria writes docs — Mon, 11 Dec 2023 14:29:31 +0000

Clear, concise, complete, consistent, correct, and consumable: these six critical attributes elevate technical documentation from average to outstanding. Their role is paramount to achieve the ultimate goal of technical documentation which is to transfer knowledge so that readers learn to use your product with the least amount of friction. By incorporating the "Six C's" into your writing process, you can develop high-quality documentation that users will continually reference. Let's explore the significance of each element.

Clear

At its core, exceptional documentation articulates even complex information with clarity. Succinct sentences and defined technical terms pave the way for understanding. Procedures are explained with unambiguous language, detailing concrete actions and ordered steps. Images complement the text, providing visual reinforcement where valuable. This emphasis on clarity allows users to find solutions quickly, bypassing dense and cumbersome passages.

Concise

Fluff finds no home in concise documentation. It delivers the precise amount of information readers require – no more, no less. Strong verbs and streamlined sentences eliminate redundancy, ensuring efficient information absorption. This focus on conciseness empowers users to extract knowledge in less time, saving them from navigating verbose and distracting content.

Complete

Truly exceptional documentation leaves no information gap.It meticulously incorporates every step, contingency, note, and resource that users might need. To achieve this level of completeness, extensive testing is crucial, uncovering any missing pieces and ensuring a comprehensive user experience. Complete documentation empowers users to achieve their goals with confidence and independence.

Consistent

Consistent formatting fosters intuitive usability by establishing recognizable patterns. Uniformity becomes the hallmark, evident across headers, images, cautions, notes, and numbered lists. Tone and terminology remain aligned, building a cohesive experience. Leverage a style guide, whether your organization's own or a publicly available one like the Google Developer Documentation Style Guide or GitLab Documentation Style Guide, to ensure consistency across your documentation. This consistency fosters understanding while minimizing confusion, guiding users effortlessly through the information landscape.

Correct

Accuracy is the cornerstone of trust in documentation. Double-checking facts and meticulously testing instructions are paramount to ensuring correctness. Verify that each step in your procedures produces the documented result. In a world rife with misinformation, accuracy signifies respect for users' time and expertise. It also prevents product misuse arising from erroneous instructions, building trust and confidence in your product.

Consumable

Consumable documentation removes accessibility barriers, making it available to all users. This includes incorporating text alternatives for images, ensuring sufficient color contrast, optimizing for various platforms, and employing plain language. Semantic HTML tags enable screen readers to effectively interpret and communicate the content. Additionally, metadata and keywords enhance search functionality, making your documentation easily discoverable. By monitoring user behavior on your documentation website, you can further refine its accessibility and usability.

Conclusion

By integrating the Six C's into your technical writing, you elevate the effectiveness of your documentation to a new level. Users receive the precise support they need to wield your product with confidence and competence. In turn, organizations benefit from efficient knowledge transfer and a more empowered user base. Make the Six C's your documentation blueprint, and watch your user experience flourish.

Book Review: "The Fine Art of Technical Writing" by Carol Rosenblum Perry

Valeria writes docs — Thu, 30 Nov 2023 00:55:19 +0000

If you're someone who has ever struggled with writing technical documents or wants to improve your technical writing skills, then "The Fine Art of Technical Writing" by Carol Rosenblum Perry is a must-read. In this comprehensive guide, Perry shares her expertise and insights, offering valuable advice and practical tips for becoming a more effective technical writer.

One of the standout features of this book is Perry's ability to break down complex concepts into easily understandable terms. Whether you're a beginner or an experienced technical writer, you'll find value in her explanations of how to communicate nonlinear ideas and build content through nested sets of grammatical constructions. Perry's clear and concise explanations make abstract writing concepts more accessible, allowing readers to grasp the principles of technical writing with ease.

Perry's skillful comparison of a well-written document to a vertebrate creature is truly remarkable. The metaphor emphasizes the importance of order, conciseness, and vigor in writing, drawing parallels between the skeleton, body mass, and muscle tone of a creature and the structure, content, and style of written text. Through this metaphor, Perry provides writers with a visual representation and a framework to create clear, concise, and engaging writing.

To honor the metaphor, I created this infographic as a visual tool to internalize the concepts presented in the book. It illustrates Perry’s unique and captivating approach to guiding aspiring technical writers in honing their craft.

Just as a skeleton provides structure and support to a living being, a well-structured document allows ideas to flow naturally from one to another. Perry emphasizes the importance of creating a stable framework by organizing information hierarchically, based on factors such as time, sequence, progression, space, importance, or categories. By following this approach, writers can ensure that their ideas are presented logically and coherently, leading to a more impactful and engaging piece of writing.

Conciseness, another crucial aspect of technical writing, is likened to the body mass of the creature. Perry emphasizes the significance of making every word count, eliminating unnecessary words and overlap. By doing so, writers can achieve clarity and avoid wordiness in their writing. The book provides practical tips on how to compact elements and nest structures to further enhance conciseness, ensuring that the message is conveyed effectively without unnecessary fluff.

Moving on to the concept of vigor, Perry draws a parallel between it and the muscle tone of the creature. She highlights the importance of empowering words and varying sentence types to maintain reader engagement. Loaded verbs and judicious use of passive voice are presented as powerful tools to create clear and specific writing. She discusses the use of passive voice for sentences whose emphasis does not rely on the doer. By employing these techniques, writers can enhance the overall vigor of their work, capturing the attention and interest of their audience.

In the final section, Perry offers valuable advice on revising and proofreading your work. She emphasizes the importance of taking breaks and getting feedback from others to gain fresh perspectives. By stepping away from your writing and revisiting it with a fresh mind, you can identify areas for improvement and make necessary revisions. Perry provides practical tips for proofreading, highlighting the importance of accuracy and euphony. By reading your writing aloud and paying attention to rhythm and melody, you can ensure that your writing flows smoothly and is pleasing to read.

Overall, "The Fine Art of Technical Writing" is an invaluable resource for anyone involved in technical writing. Carol Rosenblum Perry's expertise and practical guidance make this book a must-have for both aspiring and seasoned technical writers. Whether you're looking to improve your technical writing skills or seeking guidance on specific aspects of the writing process, this book provides a comprehensive and accessible guide. So, grab a copy, sharpen your technical writing skills, and take your writing to the next level!

Rating: 5/5 ⭐⭐⭐⭐⭐

Basics of Git explained with a concept map

Valeria writes docs — Fri, 03 Nov 2023 23:28:58 +0000

If you want to master something, teach it.

-- Richard Feynman

In April 2022, I joined the Write the Docs Slack Channel, and right off the bat, I joined my first book club. I was looking for resources to learn Git, so finding out that the book club was about "Learn Git in a month of lunches" by Rick Umali was a fortunate stroke of serendipity.

Progressing at a pace of around two chapters per week, it took almost nine weeks to peruse the book. The book is an excellent step-by-step walk-through of Git and Umali has a simple and effective way to teach how to work with Git using the Git Bash and the Git GUI. Every chapter contains graphic illustrations, screenshots, hands-on exercises, and labs to delve deeper.

In this post, I use what I learned from the book to try to explain the basics of Git with a concept map.

What is a concept map?

In this section, I will give a brief description of concept maps. If you are already familiar with concept maps, you can skip to the next section.

A concept map is a graphical tool that uses concepts and relationships to represent knowledge that answers one or two focus questions. We use boxes or circles to illustrate concepts and lines to represent their relationships. So far, this description does not differ much from a mind map, so here is the first distinction: the relationships between concepts have linking words or phrases. Connecting concepts with linking words produces meaningful statements.

Another distinctive characteristic of concept maps is that they are hierarchical, with the most general concepts located at the top of the map and the most particular ones at the bottom. We also structure texts hierarchically, which is why concept maps can help organize knowledge into a coherent structure. Describing a concept map in written words should render a logically consistent and well-structured text.

I will devote a separate post to advocating for concept maps (stay tuned for that! ). But let me point out that linking words and hierarchy are my favorite features of concept maps and why I prefer them over mind maps to represent knowledge.

Concept map focus questions

The focus questions I tried to address in this concept map are the following:

What is Git?
How does Git work?

I will explain the map following the hierarchical structure and add information and figures wherever pertinent. The concepts and git commands used in the concept map will be highlighted. Other concepts that are not included in the map itself but are relevant to the explanation will appear in bold letters. Let's start!

A concept map to explain the basics of Git

Git is a distributed version control system. But what is a distributed version control system? I will first explain what a version control system (VCS) is.

VCS is software for tracking and managing the changes made to a file or group of files (i.e., a project) over time. You save changes in a Word document by clicking a button that overwrites the changes on your file. But saving file changes in Git is broken down into two steps. First, you tell Git to track (or stage) a file with the command git add. Second, you save your work with the command git commit.

Git sees every file in your working directory as one of three things:

Tracked: a file that has already been staged.
Untracked: a file that has not been staged.
Ignored: a file that Git has been told to ignore.

Files (or changes) "move" among three different areas. The command git add moves files from the working area to the staging area where Git can "see" them. When your changes are ready to be saved, git commit moves them to the Git repository. You can reverse this flow from the Git repository to the staging area with git reset and from there to the working directory with git commit.

But what are the working directory and the Git repository?

Git tracks and manages changes in a directory called Git repository. In Git, we refer to a working directory as the local directory that contains the files of the project you are currently working on. The Git repository is created with the command git init and is a hidden directory inside the working directory. Creating a Git repository is the first step when working with Git on a project.

Committing a change in Git creates a snapshot of your project that is saved in a timeline, called commit history. Git assigns a unique identifier to each commit, the SHA1 ID, and asks you to add a descriptive message of the changes. Also included in the commits are the author's name, email address, and time of creation. You can access the commit history and all this information with the command git log.

With the commit history and SHA1 ID, you can use Git like a time machine. If you ever need to use a previous version, you can use the SHA1 ID to point Git to the version of your project you want to go to. If you want to compare the differences between versions to decide which one to use, you can use the SHA1 IDs and git diff. After determining the point you want to return to, you can start a new developmental path from there.

The Git time machine allows you to break the continuum of your main developmental path with a new one, called a branch. Every Git repository comes with a branch called main. Similar to creating parallel universes, you can start a tangent branch to test changes without affecting your project. Create as many branches as you want and save them in your Git repository with git switch -c +[branch name] or git checkout +[branch name] -b. If the changes of the new branch deserve to live in the main branch, use the command git merge to incorporate the new branch into main. Switch among branches with git switch [branch name] or git checkout [branch name].

Now it's time to revisit the definition of Git and explain when a VCS is distributed.

A VCS is distributed when each collaborator can create a copy of the original repository (which we call origin) and have the same capabilities as everyone else. In Git, collaborators have total access to a repository's history, create any number of branches, and perform any operation without special requirements. The command git clone is responsible for creating clone repositories.

Local and remote repositories are relative terms. The local repository is wherever you are working on. If you are working on a clone, the remote repository is the one from which it was cloned (the origin). If your local repository is the origin, then the remote repository is the clone.

Let's assume that the project you're working on has another collaborator, John. You and John work on their local repositories, but John has sent his changes to the origin repository first. How do you update your repository to the latest version of the original repo? And how do you send your changes to origin so that John can access them?

Synchronization of the local and remote repositories is a two-step process. The git push command publishes your local changes to a remote repository. In contrast, git pull lets you pull changes from a remote repository. git pull is further divided into two steps:

Git retrieves (fetches) the upstream changes and laids them on top of your repo. You can do this yourself with git fetch.
Git merges the fetched changes into your local repo. The command for this step is git merge.

Commands like git fetch and git merge come in handy when a commit conflict occurs. If you and John have modified the same lines of a file, called commit conflict, Git cannot determine what is correct and will ask you to solve the conflict. You will have to use the git fetch command. Then, you can use the command git diff to see the differences between your file and John's. Once you've decided how to solve the commit conflict, you can use git merge to complete the syncing process.

We’ve concluded the explanation of the concept map. If you’ve read to this point, thank you, I hope you find it useful.

What is Git? How does Git work? Here’s a summary:

Git is software to track and manage changes to files.
Git is distributed, meaning that collaborators can clone repositories and have complete control over their local repository.
Git allows people to collaborate by syncing updates among repositories.
Git is like a time machine that can take you to previous versions of your repository and allows you to create tangent developmental paths.

Final thoughts

To keep this map concise, I had to leave out many important things about Git. Choosing which things were crucial to explain the basics of Git was not an easy task. But I hope I achieved my goal of explaining clearly and concisely what Git is and how it works.

I invite you to keep learning about Git. Resources are abundant on the internet, but here are a few personal recommendations:

Book: "Learn Git in a month of lunches" Rick Umali.

Game: "Oh, my Git".

Blog post: "Git Purr! Git commands explained with cats".

Finally, I hope this example illustrates how helpful concept maps are and that you now feel curious to try them. As a visual person who enjoys structuring information, building this concept map required lots of creativity. And it proved to explain something, you need a clear understanding of the topic.

DEV Community: Valeria writes docs

Digital necromancy: zebras 🦓, ghosts 👻, and the bitter lesson

Top 5 online mentorship platforms for technical writers

Top 5 online technical mentorship platforms

The Good Docs Project

Hackmamba Creators Community

Write The Docs

WriteTechHub

Tech Writers

The perks of wearing the mentor hat

Skills you develop as a mentor

Conclusion

Top Job Posting Boards for Developers (Hint: Not LinkedIn)

DevRel Careers

Features and benefits of DevRel Careers

Otta

Features that make Otta attractive to look for a job in the tech industry

Built In

Key features that make Built In a helpful job-hunting tool

Additional recommendations

How relying on one platform could cost you your dream tech job

Conclusion

Navigating the Complexities: Challenges and Solutions in Mentoring Tech Writers

Why should you mentor others?

What are the qualities needed to become an effective mentor?

Challenges and how to overcome them

Conclusion

The Product is Not Docs, But Treat Docs Like a Product

Finding the right learning approach

How concept maps can help create clear and concise technical documentation

Understanding concept maps

Organizing knowledge

Structuring complex systems

Enabling collaboration

Conclusion

How can I learn to write simpler code?

Creating Standout Documentation: The Six C's of Technical Writing Excellence

Clear

Concise

Complete

Consistent

Correct

Consumable

Conclusion

Book Review: "The Fine Art of Technical Writing" by Carol Rosenblum Perry

Basics of Git explained with a concept map

What is a concept map?

Concept map focus questions

A concept map to explain the basics of Git

Final thoughts