Forem: Laura Grassi

🚀 Emmet in VSCode ✨

Laura Grassi — Tue, 25 Jun 2024 00:32:15 +0000

"The odds are never impossible.. Merely unfavorable

Emmet is an integrated tool in Visual Studio Code that helps us write HTML and CSS code more quickly. It allows us to expand simple abbreviations into complete code blocks, saving time and reducing repetitive typing. ⏱️

Key Features of Emmet 🛠️

Abbreviation Expansion: Transform abreviations into complete code. 📝
Code Snippets: Shortcuts that quickly insert predefined code structures. ⚡
Fast Navigation and Editing: Allows quick navigatio and editing of similar elements within the code. 🏃‍♂️

Practical Examples of Abbreviations 🔍

1 - Create a div with a specific class and/or ID

Abbreviation: .className or #idName
Example: Typing .container and pressing Enter expands to: html <div class="container"></div>

2 - Create an unrdered list with items

Abbreviation: ul>li*3
Example: Typing ul>li*3 and pressing Enter expands to: html <ul> <li></li> <li></li> <li></li> </ul>

3 - Create a link with text

Abbreviation: a[href="link"]{text}
Example: Typing a[href="https://example.com"]{Test} and pressing Enter expands to: html <a href="https://example.com">Test</a>

4 - Basic HTML structure

Abbreviation: !
Example: Typing ! and pressing Enter expands to the basic HTML structure.

5 - Create a paragraph with text

Abbreviation: p{text}
Example: Typing p{This is a paragraph} and pressing Enter expands to: html <p>This is a paragraph</p>

6 - Create an image with src and alt attributes

Abbreviation: img[src="path"][alt="description"]
Example: Typing img[src="image.jpg"][alt="Image description"] and pressing Enter expands to: html <img src="image.jpg" alt="Image description">

7 - Create a form with input field and submit button

Abbreviation: form>input[type="text" name="name"]+button[type="submit"]{Submit}
Example: Typing form>input[type="text" name="name"]+button[type="submit"]{Submit} and pressing Enter expands to: html <form> <input type="text" name="name"> <button type="submit">Submit</button> </form>

8 - Create a structure with child elements (more than one element)

Abbreviation: .container>a+p
Example: Typing .container>a+p and pressing Enter expands to: html <div class="container"> <a href=""></a> <p></p> </div>

These are just a few examples of what you can do with Emmet in VSCode. The efficiency provided by these shortcuts can significantly transform your routine. 💡

May the force be with you all. bye-bye

🎯 Strategies for Effective Urgent Ticket Classification

Laura Grassi — Fri, 31 May 2024 14:38:28 +0000

"When everything is urgent, then nothing really is."

Dealing with urgent tickts is a frequent reality to maintain the efficiency and also functionality of systems. But what exactly are urgent tickets? And how can we ensure that only genuinely critical tickets receive this classification?

I've worked for several companies that misunderstand the concept of urgent tickets, and that usually leads to a variety of complications... Urgent tickets are often misinterpreted as an invitation to prioritize quantity over quality, resulting in rushed solutions that may not fully address the issue at hand. This approach can lead to increased error andfrustated customers.

🎯 What Are Urgent Tickets?

Urgent tickets are requests or issues that require immediate attention due to their significant impact on business operations, data security, or user experience. These tickets are categorized as urgent becuse if not resolved quickly they can cause serious damage to the company or customers.

🔍 Criteria for Classifying Urgency

To determine ifa ticket should be classified as urgent we consider several criterias:

Business Impact 📈: Affects critical operations or prevents users from performing essential tasks.
Security 🔒: Involves vulnerabilities that could be exploited compromising data integrity.
User Experience 💻: Affects a large user base or causes severe degradation in the user experience (A lot of folks don't realize how crucial user experience is but it's really a big deal. If a system isn't easy and enjoyable to usecustomers might ditch it for something better).

These criteria help prioritize issues that truly need a quick and efficient response.

🗣 Helping Non-Technical People Understand Urgency

The "trickiest" thing about urgent tickets is when people who aren't tech get involved. It's always more complex for them (no doubt). But, we've got ways to lend a hand, at least to help them see that not all tickets are as urgent as they might think.

Use Clear Examples 📝: Describe concrete situations where urgency was necessary and the impacts of not addressing the issue immediately (you can try to using some no-really-related topics to exemplify) .
Measurable Impacts 📊: Use data and metrics to illustrate the severity of the situation (likerevenue loss, increased churn, or security breaches).
Visual Tools 🎨: Charts, infographics, and diagrams can help make explanations more understandable.

🏷 Subcategories of Urgency

Yes, there are different levels of urgency that can be classified to further prioritize tickets. Typical subcategories include:

Critical 🚨: Requires immediate resolution, usually within hours. Examples include system failures that halt business operations or major security breaches.
High ⚠️: Should be addressed within one business day. These are serious problems but do not completely paralyze operations.
Medium ⏳: Can be resolved within a few days. These tickets are important but do not cause immediate and severe interruptions to operations.

⏱ Average Resolution Time

The resolution time for an urgent ticket can vary depending on its complexity, but here are some general guidelines:

Critical Tickets 🚨: Expected to be resolved within 24 hours.
High Urgency Tickets ⚠️: Should be solved within 1 to 3 business days.
Medium Urgency Tickets ⏳: Can be resolved within a week.

These response times help ensure that the most severe issues are addressed with the necessary priority.

🛠 Tools and Practices for Managing Urgent Tickets

Implementing efficient tools and practices can sreamline the management of urgent tickets:

Ticketing Systems 📋: Use robust ticketing systems like Jira (one of the most popular), Zendesk, orServiceNow to track and manage tickets efficiently.
Automated Alerts 📣: Set up automated alerts to notify the relevant teams immediately when an urgent ticket is raised (We usually set this alerts on a slack channel, really useful)
Regular Training 🎓: Conduct regular training sessions for the support team to handle urgent tickets effectively (this one it's REALLY hard to implement but everyone can dream, right?).

🤝 Best Practices

Regular Updates 🔄: Provide regular updates on the status of urgent tickets to all stakeholders (one's of my favorite approachs).
Clear Communication Channels📞: Establish clear communication channels between technical and non-technical teams.

📈 Metrics and Reporting

Tracking and analyzing metrics can help improve the handling of urgent tickets:

Resolution Time ⏲️: Monitor theaverage resolution time for each urgency level (This can even become one of your future OKRs to work on).
Customer Satisfaction 😊: Measure customer satisfaction through surveys after ticket resolution (I worked in really few companies that used that).
Ticket Volume 📊: Track the volume of urgent tickets over time to identify trends and potential systemic issues.

🚀 Conclusion

Effectively managing urgent tickets is crucial for maintaining the stability and security of systems. By educating non-technical teams about the importance andcriteria of these tickets, we achieve more efficient collaboration and quicker responses to critical problems.

Master Your Code with ESLint Configurations 🚀

Laura Grassi — Wed, 21 Feb 2024 14:33:50 +0000

In a galaxy not so far away, where lines of code are the battlegrounds and bugs lurk in the shadows, a new hope emerges for developers seeking code perfection. Behold, the power of ESLint configurations, the Jedi masters of code quality!

Introduction

As you embark on your coding journey, navigating the treacherous paths of syntx errors and formatting inconsistencies, fear not! With the Force of ESLint by your side, you shall conquer all challenges and emerge victorious.

What is ESLint?

Ah young padawan... ESLint is like a lightsaber for code warriors! Imagine it as a wise Jedi master, vigilant over your code, detecting syntax errors, formatting inconsistencies, and even warning about dangerous practices. With its settings sharp as blades of light, it guides you on the journey through the galaxy of development, ensuring that your code is as impeccable as the teachings of the Jedi Order (a lit bit dramatic but you got it).

Configurations

- The Jedi Order - Airbnb Configuration 🏠:
Guided by the wisdom of the Jedi Council, the Airbnb ESLint configuration sets the standard for code excellence. With its focus on clarityconsistency, and best practices, your code shall be a beacon of light in the darkest of repositories. This configuration enforces a strict set of rules derived from the Airbnb JavaScript Style Guide, promoting a clean and readable codebase. Some common rules include:

indent: Enforces consistent indentation.
quotes: Enforces the use of single or double quotes consistently.
semi: Enforces the use of semicolons at the end of statements.
comma-dangle: Enforces consistent coma usage in object and array literals.
no-unused-vars: Flags unused variables to reduce clutter and improve code clarity.

- The Rebel Alliance - Standard Configuration 🌟:
For those who dare to defy the norm, the Standard ESLint configuration is your rebel cause. Simple, yet powerful, it challenges conventions and champions a code revolution like no other. The Standard configuration is opinionated, providing a baseline set of rules that are widely adopted across the JavaScript community, fostering consistency and reducing cognitive overhead. Some common rules include:

eqeqeq: Enforces the use of strict equality (===) over loose equality (==) to prevent unexpected type coercion.
no-undef: Flags variables that are used without being declared to catch potential bugs.
no-console: Flagsthe use of console.log() and other console methods in production code to encourage the use of proper debugging techniques.
no-unused-vars: Flags unused variables to reduce clutter and improve code clarity.
no-trailing-spaces: Enforces removing trailing whitespace to maintain a clean codebase.

- The Galactic Empire - Google Configuration 🌌:
From the depths of the Death Star, the Google ESLint configuration commands authority and precision. With its relentless pursuit of performance and security, your code shall stand strong against any threatno matter how formidabe. This configuration adheres to the strict coding standards set forth by Google, emphasizing efficiency, scalability, and best practices derived from years of engineering experience at one of the tech giants. Some common rules include:

max-len: Enforces a maximum line length to improve code readability and maintainability.
camelcase: Enforces camelCase naming convention for variables and properties.
no-undef-init: Flags the initialization of variables with undefined to prevent potential bugs.
no-else-return: Encourages simplifying conditional statements with a single return statement to improve code readability.
require-jsdoc: Flags functions that lack JSDoc comments to encourage code documentation and clarity.

- The Force Awakens - Prettier Integration 💻:
Like a droid companion by your side, Prettier complements ESLint with its automatic code formatting. Together they form an unstopable duo ensuring that your code remains pristine and unblemished. Prettier eliminates the need for manual formatting by automatically enforcing a consistent code style, saving time and reducing friction among developers. Some common rules include:

prettier/prettier: Integrates Prettier with ESLint to enforce consistent code formatting.
arrow-body-style: Encourages consistent usage of arrow function syntax.
jsx-quotes: Enforces consistent usage of quotes in JSX attributes.
prettier/prettier: Integrates Prettier with ESLint to enforce consistent code formatting.
no-extra-semi: Flagsunnecessary semicolons to maintain a cleaner codebase.

- The Jedi Temple - React Configuration ⚛️:
Amidst the towering spires of the Jedi Temple, the React ESLint configuration awaits. Tailored for the guardians of the React realm, it empowers you to wield the Force of React with grace and mastery. This configuration provides specialized rules for React development, ensuring optimal performanceJSX syntax correctness, and adherence to React best practices. Some common rules include:

react/jsx-uses-react: Flags the use of React in JSX to prevent potential runtime errors.
react/jsx-uses-vars: Flags unused variables in JSX to reduce clutter and improve code clarity.
react/prop-types: Enforces the presence of propTypes to document component props and ensure type safety.
react/jsx-indent: Enforces consistent indentation for JSX elements to improve code readability.
react/jsx-curly-brace-presence: Enforces consistent usage of curly braces in JSX attributes to maintain a cleaner codebase.

- The Sith Lords - StandardJS Configuration ⚔️:
From the shadows of the dark side the StandardJS ESLint configuration tempts with itsseductive simplicity. Embrace its power, but beware its allure, for it may lead you down a path of chaos and disorder. The StandardJS configuration promotes a minimalistic approach to linting, enforcing a strict set of rules without configuration, allowing developers to focus on writing code without the burden of configuring ESLint. Some common rules include:

semi: Enforces the use of semicolons at the end of statements.
no-unused-vars: Flags unused variables to reduce clutter and improve code clarity.
indent: Enforces consistent indentation to improve code readability.
quotes: Enforces the use of single or double quotes consistently.
no-undef: Flags variables that are used without being declared to catch potential bugs.

- The Mandalorian Guild - XO Configuration 🌌:
Like a lone bounty hunter roaming the galaxy, the XO ESLint configuration is a strict enforcer of code standards. With its no-nonsense approach, it ensures that your code obeys the law of the land, no matter how harsh. The XO configuration combines popular ESLint plugins and presets to provide a comprehensive set of rules, guaranteeing code consistency and adherence to industry standards. Some common rules include:

indent: Enforces consistent ndentation to improve code readability.
comma-dangle: Enforces consistent comma usage in object and array literals.
no-console: Flags the use of console.log() and other console methods in production code to encourage the use of proper debugging techniques.
no-undef: Flags variables that are used without being declared to catch potential bugs.
no-unused-vars: Flags unused variables to reduce clutter and improve code clarity.

- The Wookiee Warriors - TypeScript Configuration 🌳:
Hailing from the forested moons of Kashyyyk, the TypeScript ESLint configuration speaks the language of type safety and reliability. With its strong typings and Jedi-like intuition, it protects your code from the vulnerabilities of the dark side. This configuration is specifically tailored for TypeScript projects, ensuring type correctness, enhanced code maintainability, and improved developer productivity. Some common rules include:

@typescript-eslint/explicit-function-return-type: Enforces explicit return types on functions and class methods to improve code clarity and type safety.
@typescript-eslint/no-unused-vars: Flags unused variables to reduce clutter and improve code clarity.
@typescript-eslint/indent: Enforces consistent indentation to improve code readability.
@typescript-eslint/no-explicit-any: Flags the use of the any type to encourage type-safe programming practices.
@typescript-eslint/no-empty-interface: Flags empty interfaces to prevent potential bugs and promote code clarity.

- The Jedi Consulars - Vue Configuration 🌟:
For those seeking balance in the Force of frontend frameworks, the Vue ESLint configuration offers harmony. Designed to enhance your Vue.js development experience, it brings peace and serenity to your codebase. This configuration provides specialized rules for Vue.js development, including template syntax validation, Vue-specific best practices, and optimizations for Vue component structure and performance. Some common rules include:

vue/html-indent: Enforces consistent indentation for Vue templates to improve code readability.
vue/require-default-prop: Flags missing default props in Vue components to ensure component API clarity and type safety.
vue/no-unused-vars: Flags unused variables in Vue templates to reduce clutter and improve code clarity.
vue/prop-name-casing: Enforces consistent casing for Vue component props to maintain a consistent codebase.
vue/no-mutating-props: Flags mutations of props inside Vue components to prevent unexpected behavior and promote data immutability.

- The Galactic Engineers - Angular Configuration 🌌:
Mastering the power of the Angular Force, the Angular ESLint configuration empowers you to build robust and scalable applications. With a focus on modularity and efficiency, it guides you on the path to Angular mastery. This configuration is tailored for Angular projects, enforcing Angular-specific coding standards, module organization, and best practices to ensure code quality and maintainability. Some common rules include:

@angular-eslint/component-selector: Enforces consistent naming conventions for Angular components to improve code readability and maintainability.
@angular-eslint/directive-selector: Enforces consistent naming conventions for Angular directives to maintain a consistent codebase.
@angular-eslint/no-output-native: Flags the use of Angular's native event bindings to encourage the use of Angular's event emitters for better encapsulation and reusability.
@angular-eslint/no-host-metadata-property: Flags the use of Angular host metadata properties to discourage potentially unsafe practices and improve code maintainability.
@angular-eslint/no-input-rename: Flags renamed inputs in Angular components to ensure clarity and consistency in component API.

In the ever-expanding universe of code the choice of ESLint configuration is your lightsaber, your most trusted ally in the battle against the dark side of bugs and inefficiencies. So fellow developersembrace the Force, choose your configuration wisely, and may the code be with you, always. <3

Creating "Past" Commits in Git ⏳

Laura Grassi — Wed, 14 Feb 2024 16:29:24 +0000

"Always pass on what you have learned." - Yoda

Have you ever wished you could turn back time in your version control system? With Git, you can! This nifty feature allows you to create commits and set their dates to the "past." Let's explore how this can be done and when it might come in handy.

How to Create "Past" Commits

The process to perform this magical time manipulation is surprisingly simple. Just use the following command:

git commit --date "X days ago" -m "Your commit message"

Replace "X" with the number of days you want to go back and "Your commit message" with a descriptive summary of your changes. For instance, if you want to create a commit with the date of 10 days ago, execute:

git commit --date "10 days ago" -m "Fix critical bug introduced last week"

When to Use This Feature 🤔

Retroactive Fixes

Discover a critical error in your code that slipped through a few days ago? Fear not! You can fix it without disrupting your current commit history. This feature helps maintain the integrity of your project's timeline while swiftly addressing issues.

History Adjustments for Clarity

In smaller projects or solo endeavors, you may find yourself wanting to refine the project's history for better comprehension. Creating "past" commits can retroactively reflect changes that should have been made earlier, providing a clearer narrative of your project's evolution.

Integration with Specific Workflows

Certain workflows, especially in personal or experimental projects, benefit from the flexibility of creating commits with retroactive dates. This can streamline specific tasks or align with unconventional development methodologies.

Proceed with Caution ⚠️

While the ability to manipulate commit dates offers flexibility, it should be approached with caution, particularly in collaborative settings. Altering the commit history can introduce confusion and complications for fellow collaborators. Consider the potential impact on team dynamics and operations before utilizing this feature.

Final Thoughts 💭

In my experience, the need for "past" commits has been rare, if ever-present. However, knowing that Git offers such capabilities adds a fascinating dimension to version control. Have you ever found yourself in a situation where creating a "past" commit was the solution?

Embrace the power of time travel responsibly, and may your commit history remain clear and concise!

✨ Consistency and Efficiency with .nvmrc

Laura Grassi — Wed, 14 Feb 2024 16:11:51 +0000

In the software development universe, ensuring consistency and compatibility across development environments is crucial for project success. One of the most common challenges faced by development teams is managing Node.js versions, especially in projects with multiple dependencies and different version requirements. And this is my current scenario, I work with several projects with different versions of Node.

What is the .nvmrc file? 📁

The .nvmrc file is a configuration file used in Node.js projects. It allows specifying which version of Node.js to use in a given project, ensuring consistency across development and production environments. .nvmrc is a native tool of the Node Version Manager (NVM), a popular tool for managing and switching between different versions of Node.js on a system.

How does .nvmrc work? ⚙️

The .nvmrc operates simply and straightforwardly. In the root directory of a Node.js project, you can create a file called .nvmrc. Inside this file, you specify the desired version of Node.js, for example, 14.17.0. When a developer runs the nvm use command in the terminal within the project directory, NVM automatically checks the .nvmrc file and activates the specified version of Node.js for that project.

Why is .nvmrc important? 💡

The use of .nvmrc brings several significant benefits to development teams:

Consistency: Ensures that all team members are working with the same version of Node.js, reducing conflicts and inconsistencies.
Compatibility: Ensures that the code developed is compatible with the specific version of Node.js defined for the project, avoiding compatibility issues in production environments.
Ease of configuration: Simplifies the process of setting up new development and continuous integration environments, allowing new team members to get up to speed quickly.
Error reduction: Minimizes the risks of errors related to Node.js version management, making development more reliable and predictable.

How to implement .nvmrc in your projects? 🛠️

Implementing .nvmrc in your projects is simple and requires only a few steps:

Create a file called .nvmrc in the root directory of your project.
Inside the .nvmrc file, specify the desired version of Node.js (e.g., 14.17.0).
Add and version the .nvmrc file along with your source code to ensure that all team members have access to the correct version of Node.js.

Conclusion:

The .nvmrc file is a valuable tool for ensuring consistency and compatibility across development environments in Node.js projects. By implementing .nvmrc in your projects, you can reduce conflicts, improve development efficiency, and ensure the quality of the code produced. Be sure to consider using .nvmrc in your projects and take advantage of the benefits this practice can offer to your development team. 🌟

🚀 Quick guide to set up and customize your GitHub profile README

Laura Grassi — Sun, 04 Feb 2024 22:27:34 +0000

Customizing a README in your GitHub profile can serve several purposes.

Firstly, it provides visitors to your profile with an immediate introduction to who you are, what you do, and what you're interested in. This can include information about your projects, your skills, and your goals.

Secondly, you can use the README to showcase your projects, including descriptions, screenshots, and links. This helps highlight your skills and accomplishments to anyone viewing your profile. Moreover, customizing your README allows you to express your personality and personal style, making your profile more memorable and unique. Additionally, a well-crafted README can engage visitors to your profile, encouraging them to explore your projects further, follow you, or even reach out to collaborate.

Finally, if you're working on open-source projects, a detailed README can serve as documentation for other developers who may want to use or contribute to your projects. In essence, customizing a README in your GitHub profile helps you make a strong first impression, showcase your work effectively, and connect with others in the developer community. It's a valuable tool for personal branding, networking, and sharing your skills and projects with the world.

To start, let's first create the README and add it to your profile:

1. In the top right corner of any page, select the "+" icon and click on "New Repository".
2. In "Repository name", type a name that EXACTLY matches your GitHub username. For example, if your username is "test123", the repository name MUST be "test123".
3. Optionally, in the "Description" field, add a description for your repository. For example, "My beautiful repository."
4. Select "Public".
5. Check the option "Initialize this repository with a README".
6. Click on "Create Repository".
7. Above the right sidebar, click on "Edit README".

🎨Customizing:

Use GitHub Markdown (Doc about https://lnkd.in/dej5HuCa).
Start simple (because thinking about what to write always takes time).
Language: depends on your target audience, I usually always choose English as it's the "universal language".
Your GitHub profile doesn't need to be super formal like LinkedIn (although it's important to remember that it can be seen by anyone, both colleagues and potential tech recruiters, so try not to get TOO carried away hahah).

🛡️Badges:

Badges highlight your skills (the "markdown-badges" has plenty of variety).

📝Quotes:

I'm biased because I love reading books and because of that, I have endless lists of quotes that I would like to spread around the world, but I confess that the vast majority of people don't add quotes to their profile, so like all the other items: it's a matter of taste."github-readme-quotes" automatically generates quotes for you if necessary.

✨Emojis and Statistics:

Statistics: And to be honest, this is a controversial topic, some say it's not worth it, but it's up to you... You can use "github-readme-stats" to add statistics (you can even customize your cards with different layouts and themes).
Emojis ("emoji-cheat-sheet").

♿Accessibility:

One way to improve the accessibility of your profile is by adding descriptive alternative text for your images since there are some people have disabilities, while others have slow internet connections.

💡Generators:
There are several online options for some readme generators with a slightly more user-friendly interface. Among the options are:

In the end, let creativity guide you.

⭐Crafting Effective Documentation

Laura Grassi — Fri, 15 Dec 2023 12:58:45 +0000

In this article, I will share my experience in creating documentation for a project at the company I work for, X-Team (https://x-team.com/).

Context

I am part of a project initially conceived as a platform for creators to develop "experiences" on a map with points and objectives. The initial documentation aimed to explain the functioning in a simplified manner for the creators.

Over time, the project evolved into a platform more focused on events (internal/external) and business, resulting in a considerable increase in the number of features.

Our project is extensive, full of features, and not everyone is aware of its existence. To address this, we chose to temporarily pause development and create easily understandable documentation for both developers and "creators/administrators" on the platform, members of the company's community team.

Where to start? 🏁

The most challenging part is the beginning. The key is to understand for whom the documentation is being created and its purpose.

Our documentation has become a blend of Project Documentation, User Manual, and Code Documentation, extracting relevant aspects from each to meet our needs.

This format has been helpful, providing support for those starting on the project and helping the administrative part understand goals and plans.

Documentation 📃

The organization of documentation can vary for various reasons, and these variations usually reflect the specific needs of an organization.

I strongly believe that visual elements like screenshots of the screens you are referring to are very valid, as well as some highlights in red in the image if necessary.

Use Clear Nomenclature:

Be Descriptive: Choose names that clearly describe the content of the file or folder. Avoid obscure abbreviations or technical terms that may not be understood by everyone.
Keywords: Include relevant keywords that highlight the main function of the document. This facilitates search and understanding of the context.
Consistency: Maintain a consistent approach when naming different types of documents. This creates a predictable structure that users can understand and follow.
Avoid Generic Names: Avoid generic names that do not provide much information. Try to be specific to avoid confusion.

I know these seem like extremely obvious tips, but you have no idea about the documentation I've had to read in my life 👀. By adopting clear nomenclature, we make the documentation more accessible and friendly, allowing users to easily identify what they are looking for and understand the content before even opening the files.

Categorize by Theme:

Identify Main Themes: Analyze the documentation content and identify main themes or categories. It could be related to specific features, processes, modules, or any other criteria that makes sense for your application or system.
Avoid Overly Deep Folders: Maintain a folder structure that is not too deep. Excessively nested folders can make navigation difficult. In our case, we used a maximum of three nested folders.
Consistency in Folder Naming: Just like in file naming, try to maintain consistency in folder naming.
Be Comprehensive but Concise: Ensure you create categories that cover a wide range of topics but avoid segmenting too much. The goal is to make the organization intuitive and easy to understand.
Logical Relationship: Folders should have a logical relationship to each other. For example, in our case, the page for creating items in our system is indeed within the administrator's panel and in the Library section.
General or Introduction Documentation: Consider having an initial folder containing general or introductory documents. This helps users get an overview before delving into more specific categories. In our example, the introduction was within the "Library," "Overview," "Pages," etc. sections.

Indexes and Links:

Detailed Indexes: Include detailed indexes at the beginning or strategic locations of the documentation, listing key topics or sections. (The vast majority of platforms where we usually place documentation do this automatically for you).
Navigation Links: Consider including navigation links at the beginning or end of each document, allowing users to move easily between related documents or return to the main documentation page.
Relevant External Links: If there are important external resources for understanding the documentation content, include links to those resources.

Formatting Standards:

Consistent Style: Choose a formatting style, such as fonts, text sizes, colors, and header styles, and use it consistently throughout the documentation. This creates a cohesive visual identity. Personally, I love highlighting aspects that I consider important with red colors to draw attention.
Visual Hierarchy: Use different header levels to indicate the hierarchy of information. For example, a level 1 header can represent a main section, while lower-level headers indicate subsections (If you're a frontend dev like me, I know you felt at home in this topic 😂).
Lists and Highlights: Use numbered or bulleted lists to highlight important items. Use bold or italic for relevant words or phrases.
Adequate Spacing: Create and maintain a standard spacing, because no one deserves those large spaces with lots of nothing.
Code Formatting: If the documentation includes code snippets, use consistent formatting to make the code easily understandable. The vast majority of platforms have tools for codes.
Step Numbering: When providing step-by-step instructions, use numbering.

Sustainability

Accessibility and Clarity: The documentation is designed to be accessible and understandable for different audiences, including developers and creators/administrators on the platform. The use of simple language, visual resources like screenshots, and highlighting important information contributes to clarity.

Hybrid Format: The combination of Project Documentation, User Manual, and Code Documentation meets the different needs of users, providing detailed information for developers and a more general overview for platform administrators.

Efficient Organization: The structure of folders and files is logically organized, following principles such as clear nomenclatures, categorization by themes, detailed indexes, and navigation links. This facilitates locating information and navigating the documentation.

Formatting Standards: Consistency in style, visual hierarchy, use of lists and highlights, adequate spacing, and code formatting contribute to a more pleasant and understandable reading experience. These standards help in quickly identifying important information.

External Feedback: The practice of requesting people external to the project to read and use the documentation is a valuable approach to identify possible points of confusion or lack of clarity. This allows continuous adjustments to improve the quality of the documentation.

Adaptation to Changes: The documentation was created in response to the evolution of the project, adapting to new features and changes in focus. This demonstrates the ability to keep the documentation relevant and updated as the project develops.

Emphasis on Usability: The focus on the usability of the documentation, considering the user experience when following instructions, highlights the importance of not only providing information but ensuring users can effectively use it.

In summary, the sustainability of the documentation is achieved through a comprehensive approach that considers the diversity of users, stays adaptable to changes in the project, and uses good practices of organization and formatting. These elements contribute to effective and long-lasting documentation.

Conclusion:

One of the approaches I experimented with to assess the complexity of my documentation was to ask people with no prior contact with my project to read the documentation and try to understand what it is about, as well as effectively use the system based solely on the provided instructions. This practice proved extremely useful as it allowed me to identify parts that might not be sufficiently clear, enabling necessary adjustments.

Special thanks to the X-team for allowing me to share some details of our project with you. I extend my gratitude to Lucas, who collaborated with me in creating an amazing documentation in our project, and to Patrick, who thoroughly reviewed my text here.

I hope this article is helpful for you! ❣️