Skip to content
PodSubs
ShowsPeopleGuestsJobsNewsEvents
More
BlogPodCred
Menu
ShowsPeopleGuestsJobsNewsEventsBlogPodCredNetworksSign in
Join nowSign in
  • Shows
  • People
  • Jobs
  • News
  • More
    • Guests
    • Events
    • Blog
    • PodCred
    • Networks
    Join nowSign in

Simon Shares

Simon Shares artwork

I suck at thinking of examples off the top of my head

Apr 10, 20244 minAudio
ShareXLinkedInFacebookWhatsAppEmail

Can you make your documentation more helpful please? ★ Support this podcast ★

Audio and video play straight from the show's own hosting. PodSubs stores and serves no media.

Transcript

From the show. Tap a time to play from there.

meI spent a lot of time recently interacting with some online documentation for a PHP framework that I don't use very often really. But I'm using it more right now because of a contract that I'm working on. And it kind of dawned on me how important it is to understand why various parts of a framework actually exist. And I don't mean that we all need to understand why they exist before we can use the framework. I mean, from the documentation's point of view, that it understands why or the the person who's writing it understands why that part has been built.

Because it's clear from the documentation that I've been reading, that either people either don't know why or they assume that everybody else does know why. But I think documentation is so much clearer and so much easier for people to sort of grasp. Like, especially if there's choice in in what you're writing. Like, if you're writing about a subject matter, let's say it's caching, and you've got multiple ways of doing caching. You know, you might have something that just stores, objects in memory.

Sorry for the non technical people, but you might have a way that stores them to disk or to a database. And though just those three options, that that presents so much like choice to somebody who maybe is new to this concept. What they lack is an understanding of when they should use one over another. And that's what the documentation can I'm not saying it necessarily should, in every case, help them to understand. And this is a contrived example, like most of us probably know what caching is and how, you know, the different options that are available.

But hopefully, you get the point that if the documentation is clear on the why, they can provide that context to people that are reading it. And I think that would be so much more useful. I would love to give a solid example of a situation where this has affected me with this particular documentation. But I don't really wanna call it out too much because I think overall, it's a really good piece of kit. It's just the documentation is really seriously lacking.

I wish I had time to help them sorted out because I think it only takes somebody with a little bit of thought to go in and write some, you know, an extra paragraph about this and that. But it's a it is a lot of work to kind of understand all of these topics well enough and deeply enough, and then be able to write clearly to help people. And that's the point of the documentation, is to help people. Like, especially when it comes to code, you can discover how the thing works by looking at the code. I mean, it's the same with the physical thing.

You can do you can figure out how to work a washing machine or a vacuum cleaner or, you know, an some appliance without the manual. Right? You can press all the buttons, and you can risk breaking the thing. But with the instructions, it will go so much easier. So they're there to help. So why not make it help? Start with why. Bye.

Open the transcript file

Hosts and Guests

Hosts

  • Simon Hamp Host Feed-stated

Credit the people on this episode

Be the first to rate this episode

More episodes

All episodes
  1. Enjoy the flames

    Oct 27, 202643 minAudio

    CVEs, AI, and the appocalypse ★ Support this podcast ★

    Credit the people on this episode

  2. We made it!

    Sep 22, 202637 minAudio

    Much success! ★ Support this podcast ★

    Credit the people on this episode

  3. Start With Why

    Aug 27, 202619 minAudio

    Simon Sinek should write books about PRs ★ Support this podcast ★

    Credit the people on this episode

  4. The Ten Percent

    Aug 11, 20264 minAudio

    Sturgeon's Law ★ Support this podcast ★

    Credit the people on this episode

  5. Football

    May 17, 202629 minAudio

    it's brief! ★ Support this podcast ★

    Credit the people on this episode