DEV Community: Duodu Randy 💻🐍

Why Docs-as-Code is the Key to Better Software Documentation

Duodu Randy 💻🐍 — Mon, 10 Jun 2024 14:01:33 +0000

Introduction

In the software development ecosystem, there is often friction between software developers and technical writers when it comes to creating and contributing to software documentation. One reason for this issue is that these two key players often use different methods for publishing their work. However, wouldn't it be beneficial if software developers could collaborate with technical writers in writing and managing software documentation?

The answer is YES, it is possible, but only with the Docs-as-Code approach. To understand how this can be achieved, let's dive deeper into what the Docs-as-Code approach entails.

In this post, you will learn about managing technical documentation in the same way a developer handles code, known as the Doc-as-Code (DAC) approach, and why team leaders and technical writers should adopt it.

TABLE OF CONTENTS

Introduction
Docs-as-Code (DaC)
- What is Docs-as-Code?
- Processes of the Docs-as-Code approach
- Tools used in Docs-as-Code
- The Benefits and Limitations of Docs-as-Code
- Benefits
- Limitations
Conclusions

Docs-as-Code (DaC)

In technical writing, many approaches have been used by technical writers for writing, publishing, and maintaining technical documentation. Previously, technical writers used Database CMS tools such as WordPress, Hippo, and others, which did not encourage contributions from other users, such as developers, to the documentation.

It was not until October 19, 2000, that Tom Preston-Werner, co-founder of GitHub, had an idea about the Docs-as-Code (DaC) approach.

In a blog post, Blogging Like a Hacker, he states,

"What would happen if I approached blogging from a software
development perspective? What would that look like?"

The question above gave birth to the Docs-as-Code approach.

What is Docs-as-Code?

Docs-as-code is an approach to writing and publishing documentation with the same tools and processes developers use to create code.
In short, the DaC approach uses the same systems, processes, and workflows with docs as you do with programming code.

Processes of the Docs-as-Code approach

The Docs-as-Code approach comprises:

Writing reStructuredText or Markdown in plain text files.
Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.
Working with files using a text editor that supports docs-as-code, such as Visual Studio Code.
Keeping track of the documentation in a version control repository (usually a Git repo), similar to how developers store programming code, rather than keeping docs in another space like Dropbox or a SharePoint drive. Additionally, you can store the docs in the same repository as the code itself.
Working with other writers using version control systems such as Git to track changes in the plain text files instead of collaborating through large content management systems or SharePoint-like check-in/check-out sites.
Automating the site build process with continuous delivery to build the documentation website when you update the repository, rather than manually publishing and transferring files from one place to another.
Executing validation scripts to check for broken links, improper terms/styles, and formatting errors instead of spot-checking the content manually.
Managing docs using processes similar to engineers (e.g., agile scrum), such as dividing documentation tasks in an issue manager (such as JIRA), allocating the issues to bi-weekly sprints, and informing stakeholders about the tasks finished (showing demos).

Tools used in Docs-as-Code

There are many tools that you can use with the Docs-as-Code approach. They include:

Plain text markup such as reStructuredText or Markdown. We recommend you use reStructuredText. You can read this article first to help decide which markup language to use in your project.
Static site generators like Sphinx.
Text editors that support Docs-as-Code, such as Visual Studio Code.
Git for version control and GitHub for storing remote versions of the repository.
Continuous integration and continuous delivery tools like GitHub Actions.
The Python programming language.

The Benefits and Limitations of Docs-as-Code

Using the docs-as-code approach has both merits and demerits, which you must consider before adopting it into your project. Below are some benefits and limitations of using the docs-as-code approach.

Benefits

Collaboration with developers: The docs-as-code approach improves collaborative efforts between developers and technical writers, enabling the provision of better and more accurate documentation. Often, writing documentation for a particular product is complex enough to necessitate involvement from developers for both writing and reviewing. As a result, implementing the docs-as-code approach encourages developers to contribute to the product documentation, allowing technical writers to focus on documenting how to use the product effectively.
Integration with other infrastructures: You can incorporate the docs-as-code workflow into existing company or project infrastructures. Most companies rely on certain infrastructures to operate, and any new approach they adopt must integrate seamlessly with those existing infrastructures. The docs-as-code approach is suitable for such companies because of its flexibility, making it easy to integrate into any existing infrastructure. For example, useblocks GmbH, a German software solution company, has developed a Sphinx-Needs Enterprise plugin that integrates Sphinx-Needs into company-specific tool environments. This synchronization of data between Sphinx-Needs and existing tools like Jira, Azure, GitHub, and CodeBeamer ensures the utilization of data from other existing tools with Sphinx-Needs, resulting in the generation of meaningful documentation.
Contribution from the open-source community: The docs-as-code approach embraces external contributions from other technical writers, subject-matter experts, and users. While not all documentation projects are public, most allow other contributors to participate in their development, aiding in the discovery and resolution of issues in the documentation. Although these contributions need to be reviewed to ensure they align with your style guide and content strategy, the input provided by the community helps enhance your documentation.
Continuous Delivery: In the docs-as-code approach, you can rebuild your output by simply committing and pushing content into a Git repository. The repository will detect the changes and trigger a build and publishing job, a process known as Continuous Delivery. You can edit multiple pages and send your changes to your production repository. When the changes reach your production repository, an automatic content build and deploy process runs on your repo, quickly transferring the output files to your server. You no longer need to FTP files to a server or follow a manual deployment process. A quick update and a Git commit are all you need to change your documentation. This helps reduce the pressure of publishing and deploying docs and also encourages developers to write and contribute to the documentation. Continuous delivery is the feature that makes docs-as-code so much more effortless (with publishing) compared to other solutions.
Delivery of updated and validated documentation: Using the DaC approach, you can deliver up-to-date documentation to your users, enabling them to access accurate content. For example, most Sphinx documentation sites provide information about the date of the last changes. This information informs readers if they are reading outdated content or not. Additionally, we can use validation scripts in our docs-as-code approach to ensure we validate each content before publishing it. Validation scripts, such as checking broken links or verifying if the content meets the style guide, help us identify mistakes so we can correct them.
Integration with A.I. tools: You can use A.I. tools to assist in drafting and reviewing documentation, enhance documentation search capabilities with tools like Algolia DocSearch and TypeSense DocSearch, and provide a support assistant chatbot like DocsBot AI that helps software users access information and troubleshoot problems.
Content reuse: Content reuse is the ability to include content from one document in another. Most docs-as-code static site generators support content utilization using templating languages like Jinja to enable documentation writers to use conditional filtering, content reuse, variables, and more when writing documentation.

Limitations

Here's the revised version with corrections:

The following are some limitations of docs-as-code:

Learning Curve: The DaC approach requires writers to be familiar with software development tools like Git. Additionally, most technical writers use Markdown to write their documentation. Although the Markdown language is easy to learn and use, it lacks standards. The many flavors of Markdown syntax make it challenging to use the same Markdown text across all Markdown-supported static site generators.

Note

Instead of using the Markdown language, we recommend you use the reStructuredText language.

Tool Integration: Integrating documentation tools into existing workflows can be tricky at times if best practices are not implemented.
Cultural Shifts: Both technical writers and developers must agree to the use of this approach for successful implementation.
Localization: Localization in docs means adapting your documentation to the needs of a particular language. Having your documentation in multiple languages is a requirement for a documentation site that aims to convey its message to a particular language and culture. Most docs-as-code static site generators do not support translation (except Sphinx). While we write most technical documentation in one language, it is appropriate if these docs-as-code tools support localization.
Hard to prevent Git disasters in public technical documentation: Using version control systems, like Git in the docs-as-code workflow, requires some training and a code of conduct to prevent Git mistakes in public documentation.
No PDFs: For most technical documentation, it is necessary to generate PDF documents for the entire documentation project or single pages in the documentation. PDF is possible, just not usually an out-of-the-box feature.

Note

You can try out either the Sphinx-PDF Generate or the Sphinx-SimplePDF plugin if you are using Sphinx-Doc.

Conclusions

In most companies, technical writers adopt the docs-as-code approach to write both external and internal technical documentation. Although there are challenges with the approach, if the right measures and practices are put in place, both the developers and technical writers will benefit hugely from adopting the docs-as-code approach to document up-to-date content for their software users.

Below are some best practices I would recommend if you want to adopt the docs-as-code approach in your projects:

Early Integration: Integrate the DaC approach into your documentation project early in the development process.
Automated Testing: Employ automated testing tools like PyTest, linters, and formatters in CI/CD tools like GitHub Actions to ensure documentation accuracy.
Consistent Formats: Analyze and select one or more text-based formats to use in your project and provide standards on the text-based formats selected for ease of collaboration.
Use third-party software and collaborative tools: Utilize third-party tools to ensure writers focus on writing and delivering documentation quickly and to ensure collaborative editing and review.
Additionally, create a docs-as-code ecosystem that is open to all contributors. If users contribute to the documentation, it enables a workflow where writers and users feel ownership of documentation and work together to deliver essential information.

There is more to building a proper Docs-as-Code ecosystem, and I hope to find and share such knowledge with everyone.

Kindly comment📝, like👍, and share🔗 this article if you find it informative.

Saved by `git fetch` and GitHub

Duodu Randy 💻🐍 — Tue, 25 Jul 2023 07:18:48 +0000

How to Retrieve a Discarded Commit from a Closed Pull Request

Have you ever encountered the heart-stopping moment of accidentally discarding a crucial commit during your development process? I certainly did while working on GitHub. Initially, I wanted to share my experience and knowledge on "How to Retrieve a Discarded Commit from a Closed Pull Request" in this blog post. However, after discovering a powerful solution that saved the day, I knew I had to re-title it to "Saved by git fetch and GitHub".

Objective

In this article, I'll guide you through the steps I took to recover that lost commit, sparing you from future Git stress. So let's dive in and uncover the magic behind git fetch and GitHub's functionality.

A little backstory...☁

Here's what happened: I synced a branch of a forked repository with changes from the main branch of the parent repository. In doing so, I accidentally discarded a crucial commit. Realizing the mistake, I began my quest to recover the commit but made several unsuccessful attempts.

Salvation steps 🏆

Despite the many trial and errors, I eventually found a solution that worked. I discovered the following steps that led to a successful retrieval:

First, I checked the commit history of the pull request (PR) on the parent repository associated with the forked repository. There, I found this entry: "@user123 force-pushed the Test-Feature branch 2 times, most recently from q7a4399 to wa8a5fa".
Armed with this information, I clicked on the q7a4399 commit link, which redirected me to the commit page. From there, I clicked the "Browse Files" button in the top-right corner of the GitHub page, leading me to a tree page for commit q7a4399.
On the commit page, I copied the fully spelt hexadecimal object name or the full commit ID from the page's URL. The hexadecimal commit ID looked like this: q7a439948dd813bdcdd5b153effca041d197591d.
To retrieve the lost commit, I employed the git fetch command with the following syntax:

git fetch origin +q7a439948dd813bdcdd5b153effca041d197591d:Test-Feature

The command's structure is as follows:
git fetch [<repository> [<refspec>...]]

where:

repository: Refers to the Git repository (in this case, "origin" as a shorthand for my remote GitHub repository).
refspec: Specifies which refs to fetch and which local refs to update. The format of the parameter is an optional plus "+", followed by the source <src>, followed by a colon ":", and finally, the destination ref <dst>. <src> typically represents a ref, but can also be a fully spelt hexadecimal object name. (E.g. +<src>:<dst> => +q7a439948dd813bdcdd5b153effca041d197591d:Test-Feature)

For more details on the git fetch command, you can refer to its documentation or use the "git fetch --help" command to access the manpage.

By following these steps, I successfully relieved myself from the stress caused by the lost commit.

Conclusion

In conclusion, Git is a powerful tool that requires continuous learning to improve our understanding and expertise. Take the time to explore its capabilities, and you'll find it invaluable in your development workflow.

The Software Developer 👨‍💻 and Package 📦 Loop 🔁

Duodu Randy 💻🐍 — Fri, 08 Oct 2021 11:34:02 +0000

Introduction

If you are reading this, you might think about these questions. 🤔️Should I focus on learning a software package than the programming language they built it to support? or 🤔️Should I know every detail about a software package to be employed?

If the questions above describe you, I think it is good you continue reading⬇️.

While writing this blog, I wanted to share tips that helped me improve📈️ as a self-taught developer.

One major problem that hindered my learning path📉️ was trying to memorise the software packages I used to build software apps.

About software packages

In any programming language, be it Python or JavaScript, the community builds and provides software modules known as packages. These packages help you develop your applications without knowing the low-level details of how they perform them.

Some of these packages have their communities that help improve the package. Packages like React, Django, just to name a few, host conferences to learn best practices of using these packages. In addition, job descriptions include these packages as requirements to be qualified for a job.

Because of the points above, many entry-level software developers seem to focus🧐️ on being good at using software packages which is not appropriate.

As a software developer, it is not appropriate to focus on being good at using software packages and I clarify why you don't need to below.

Reasons you don’t need to memorise a software package📦️.

To begin with, let us list my three reasons you shouldn’t focus on being good at using a software package.

The reasons are:

Software packages have a purpose.
They can depreciate over time⏳️.
They have documentation📑️.

Now let us discuss these reasons.

Software packages have a purpose

Every software package we use as developers is a tool to achieve a specific goal. For example, you can use React to build outstanding user interfaces for mobile or web applications and that will be the purpose of React for you. As a result, the important thing to know is how to apply a package to your use case.

Software packages can depreciate over time⏳️

So, just like any package at the supermarket, software packages and their functions become obsolete or deprecated. This happens to either improve software packages or create new ones that better implement the purposes of the older packages. As a result, users must update their knowledge about a package. For instance, you cannot apply the way you did things in Django version 1 to how you do it in Django version 3.

Software packages have documentation

Documentation is a manual written by the creator of a software package on how to use it. Although some creators do not write good documentation, your ability to read documentation can guide you on how to apply a software package. As a result, it is important to learn how to access this documentations and well use it.

Tips on how to overcome the problem of memorising software packages 💪️

The list below helped me to get out of the software package loop and you can try it.

You must have a use case for a software package. A use case will guide you on how best to learn and apply the package. For instance, a project may require you to build an E-commerce site for a large-scale business. This use case can guide you in selecting a software package like Django.
You must develop the habit of reading package documentation. The habit to access and read package documentation can help you apply a software package to a use case.
You must focus on learning the programming language. This is because the packages revolve around the programming language and not vice versa. For example, if you know JavaScript, you can learn and understand React or any JS package. This is because the React team built React using JS.
Also, your knowledge about a programming language can help you contribute to improving the package. For example, if you know JavaScript, you can contribute code to any JS package.
You must write notes about how you used a package to solve a problem. These notes can serve as a reference to you later.

Conclusion

In conclusion, you shouldn’t focus on learning a software package than the programming language they built it to support. Also, you shouldn’t know every detail about a software package to be employed.
You being able to apply a package for a particular use case is important than memorising it.

What are your thoughts about this topic? Also, what are some tips that helped you grow as a software developer? Share your answers in the comments section.

If you enjoyed this blog, do well to like 💜️ and share it with friends. Also, follow my account for more interesting blogs and consider following me on Twitter🐦️ and LinkedIn account for more developer-related content.

What did I do wrong? 😓

Duodu Randy 💻🐍 — Mon, 06 Sep 2021 01:25:09 +0000

A story about an entry-level developer's frustration

⏰ Woke up one day 🌅 feeling good, cause meeeen! I wanna be a software developer 🧑‍💻

🔎 Searched on Youtube, learnt the basics, created some demos 📁. Ooh! nice 🤩 Dev ain't bad at all

Joined some boot camps 🏕️, made some dev friends 🧑‍🤝‍🧑. Oh Wow! this s**** is awesome

Wanted more so I bought 💵 some courses, created a Twitter account cause TechTwitter they said was the best

🤝 Followed some folks, got some tips and yeah TechTwitter is the best

Kept on learning 🐱‍👓 and practising more because practice they say makes one perfect

So it has been some years and I felt like yoo! I got this. Let me apply for some jobs 👔

Started writing some CV's 📋✍️, created a LinkedIn 👤 account to apply for jobs related to my tech stack

Applied for internship jobs, freelance jobs, entry-level jobs, like all the jobs I could think of

Was at this point that I knew s**** 💩 is getting crazy

Went through the mail, got plenty of rejected 🙅 applications. For some, I don't know when they are going to reply

Maybe when Thanos grows a moustache 🥸

Started getting frustrated 😔. Imposter syndrome kicked in. F**** I have to put food on the table, why me?

DMed some folks for advice. I continued sharpening 🏋️ my skills cause I had the belief things will be fine

Thought of startups so I started. It failed but I learnt. We move 🚙

Volunteered to build apps for some friends and organisations to improve my experience. Some rejected and others accepted

Added the volunteered work to my CV and started applying for some jobs because I spent the little I had on improving my skills

Finally, I got some replies 📫 with links to the code test. Felt glad.

Opened the replies 📬 and what 🤯! I get these scary questions to answer

Tried my best, got some answers right, submitted my response ↩️, and hoped 🤞for the best

Results came back and I failed ❌ but I realised I needed to learn hard if I want far

Not having enough resources to purchase some courses and data bundles, I depended on late midnight bundles, torrents, free courses, and Youtube courses

Developed a portfolio site, updated my CV, and improved my LinkedIn, GitHub, and Twitter accounts with some tips

Doing all this and still, no jobs started hitting me hard 😞. All I wanted was to do what I liked while getting paid

Began to doubt me 🤦, see TechTwitter as showoffs, and losing passion and love for development

Some will say I was after the money but sincerely speaking who does not want to enjoy their hard labour

After some time ⌛, I decided to quit. I stopped coding, stopped learning skills, and stopped focusing on my career path

I called a friend to talk to and the encouragement I got made me realise that I must keep on fighting

So I resumed my software development career and something 😲happened one day

I got an alert and it made me happy 😃

The alert was from Google Photos and it was an OTD picture. The picture was about a URL cutter ✂️⛓️ project I did during the early stages of learning development

I laughed and said I have come far.

So though you haven't crashed ®️ the jobs yet and you don't know what you are doing wrong 🤷 it is ok

DEV Community: Duodu Randy 💻🐍

Why Docs-as-Code is the Key to Better Software Documentation

Introduction

Docs-as-Code (DaC)

What is Docs-as-Code?

Processes of the Docs-as-Code approach

Tools used in Docs-as-Code

The Benefits and Limitations of Docs-as-Code

Benefits

Limitations

Conclusions

Saved by `git fetch` and GitHub

How to Retrieve a Discarded Commit from a Closed Pull Request

Objective

A little backstory...☁

Salvation steps 🏆

Conclusion

The Software Developer 👨‍💻 and Package 📦 Loop 🔁

Introduction

Reasons you don’t need to memorise a software package📦️.

Software packages have a purpose

Software packages can depreciate over time⏳️

Software packages have documentation

Tips on how to overcome the problem of memorising software packages 💪️

Conclusion

What did I do wrong? 😓

A story about an entry-level developer's frustration

👍YOU GOT THIS💪