loading...
Cover image for Perfect Documentation

Perfect Documentation

james_foran profile image James Foran ・2 min read

So you have taken the bait. Documentation really is the hottest topic in tech right now 😼.

This post is inspired by the podcast Enjoy the Vue where they discussed in detail the documentation process. Check out [episode 30(https://enjoythevue.io/episodes/30) for all the gory details! Thanks Natalia and Sam and the rest of the team at Enjoy the Vue! Now lets dig in to this very high level process 😜.

The Process

Documentation Process

Crap Documentation (docs)

You have to start somewhere.. and documentation will always be less than ideal to begin with. There are no shortcuts too good documentation either. Don't expect your first draft to be close to good. Just do it.

Review

After you have completed your personal review, you need the documentation to be reviewed by others. This will include SME's (subject matter experts) and people who represent the intended audience. If you don't have people available to review it, publish it. You can then incorporate feedback from readers feedback.

Good Documentation

After many reviews, and feedback from readers, documentation can get to a good state. Be careful though, this will not last. As time passes, documentation can quickly become outdated, and will become crap documentation again in no time.

Perfect Documentation

While its an honorable goal, no documentation will ever be perfect. Maintaining good documentation is a lot of work in itself. But the benefits of maintaining good documentation are huge.

I think much of the success of VueJS today has to do with its great documentation. Yes, its great, and that is because there are so many contributors. Over 700 people have contributed to the Vue docs.

I think documentation can help in many ways. I also like to document stuff before I start developing in some cases too. It helps me to frame my thoughts, and keeps me focused if I get stuck on a technical issue that takes me down a rabbit 🐰 hole.

And, this document is in the "crap" phase itself. I would love for you to review it, and provide feedback below. Perhaps together we can make this process "good".

Posted on by:

james_foran profile

James Foran

@james_foran

Passionate about solving problems and helping people.

Discussion

pic
Editor guide