Documenting your Project

One of the creators I support on Patreon, wrote a post about how it is hard to write documentation.  And I have to agree, it is often the worst part with any project that I’ve had to deal with.

There are a few different parts that I think a lot of people fail to understand about documentation.  There are certain goals that you want to accomplish and that’s a lot more difficult when you don’t understand that you have to separate different types of documentation.

There tends to be different divisions that people talk about depending on what the focus is.  If we’re talking about something like an open source project one division would be:

  • Marketing material
  • User material
  • Developer material

I would say this is a fair division, but it really isn’t breaking it up in terms of how the documentation functions.  I’m taking a bit of a stab at this in terms of functional purposes:

  • Technical specifications
  • How to instructions
  • Component documentation (man pages?)
  • Philosophical documentation (why things are the way they are)

To be functional in terms of technical writing, and actually being useful, you need to separate these things out.  I’m not really that great at figuring out how to do that, as I tend to muddle stuff together kind of naturally.

A good way to understand if the documentation is good is when someone asks, “how do you do X?” can you point easily to a how-to about how to do exactly that, or say, “That’s a bit complicated, and you need to look at this manual which explains the details of programme Y?”  or, “You are trying to interface programme A with programme B, and you’ll need to look at the specifications for the API of both of them here… and here…”

If the go to answer is, “look at this 90 page document and that explains that one simple thing” then first off the documentation is poor, and there is a culture that it doesn’t really matter that the documentation is poor.

I’d really like to say that I feel that what I’ve said here is useful, and will help people figure out how to do good documentation.  But I think at best, it might be helpful to realize that the reason that the documentation isn’t “working” is because it actually isn’t good documentation.

Maybe?  If I broke down those bullet points, and found ways to talk about what they end up meaning it could prove helpful.  I feel that each of those 7 bullet points could easily be at least as long as this, to come up with a good starting place to work with them.  Possibly breaking further into similar numbers of similar sized pieces.

This would be a decent start to consider going further with this…  If someone else wants to do so, or whatever.  Maybe some time if someone contacts me (however they would) about something they’d like to hear me say more about, that I’d expand this out…

Posted in Uncategorized | Comments closed

Why not to use the Block/Gutenberg editor.

Orriginally this was a comment on the Yoast Post about Why to Use the Block Editor, but their comment form doesn’t tell you how long they can be, doesn’t tell you how long it is, so this will be the extent of the comment I will leave, with what will be a, “you need to save people from wasting time by saying *afterwords* that a comment is too long, with no indication of how long, “short enough” is.”

Your, “this is better” reads a lot like, “use this because it has all the shiny bells and whistles.” Maybe I’m missing something in my reading.

I do *not* use a plugin to put tables in while I’m using the “classic editor”. But apparently what I’m doing (by your writing) is simply not possible.

I won’t say that it is *easy* but there’s a big difference between, “not easy” and “not possible”.

A big problem with the development of WordPress has been that it ended up doing *too much* and part of how that got addressed was to provide the theme, and plugin functionality.

Your argument *for* the block editor is that it will eliminate the need for plugins and themes. This feels like a reasonable argument for saying maybe people should simply be moving away from WordPress.

Many of my clients have limited resources, and WordPress simply will not run on a low resource VPS successfully (possibly not even at all without doing stuff like massive amounts of swapping, but certainly poorly). It’s not as resource heavy as Mastodon, Matrix, or PeerTube, but it seems that it is moving more and more into higher resources, rather than lower.

When speaking of SEO, one of the *biggest* factors (according to Google, but apparently not according to you) is the speed at which you can provide content. WordPress needs large resources to compare in speed to a well developed system focused on what a client needs, rather than providing “everything you might want”.

I have replaced, “easy solutions” like Typeform, with *poor* quality code, and had performance improvements of 30-100 times faster to do the same thing. And the “block editor” feels very much like something like this on at least another order of magnitude performance hit.

This also is a thing which is pretty much why we are *hoping* to move away from WordPress for future sites entirely.

Posted in Web Development | Comments closed

Some of Why I Don’t Recommend Gentoo

First off, I really like to work with Gentoo myself.  So, it’s not really that I have a problem that I don’t like Gentoo, but rather, that I have problems with the community, and somewhat with how Gentoo itself tends to work for most people (ie. it fundamentally can be quite frustrating).

The Community

Initially, I started using Gentoo, in part because of the community.  Generally when I wanted to get something answered, I could either find the answer, or have someone who would be willing to help me with it.

Part of that was that really I could find the answer without having to work through a lot of stuff that just didn’t make sense, or was written in such a way that figuring out all the steps was too difficult.

Now?  I can say quite definitively, that it’s not worth asking the community for an answer.  Too often the answer is, RTFM, and they think that the “material” is “fine” but in reality, it’s more the other kind of “f” material.

The Handbook, when printed is about 150 pages.  Which, of course, as itself, isn’t really a problem.  But, the thing is, they say, “It’s in the Handbook” or, “Nobody follows the handbook” and when you point out that there’s plenty of reasons that people aren’t following the handbook, they basically tell you, “go ahead and rewrite it”.

If, the community was actually helpful, and would say, “here, this is where you can find the information in the handbook,” rather than, “It’s in the handbook, go read it.” Mind you, if they actually did do that, then of course, they would start to understand that the documentation is not as good as they claim it to be.

Project Documentation

A big part of this specific issue, is that (like many projects) the documentation is actually poorly understood, by the people who are producing it.

Writing good documentation is actually a tricky, and requires understanding what the role of a given documentation is.

The 150 page Handbook, has explanations, how-tos, technical information, and opinions all in a single document.

This is a commonly produced document, but it’s not really that useful of a document.  The main (stated) goal of the Handbook, is to allow people to setup Gentoo, and then move on from there.

This should be written in a style like:

  1. Measure matcha into sifter
  2. Sift matcha into chawan
  3. Add small amount of water to matcha in the chawan
  4. Whisk the matcha and water together to form a smooth paste
  5. Add more water to the matcha paste
  6. Whisk to a frothy mixture
  7. Enjoy

And while that is getting there, I would probably say that is missing some stuff in various parts, which would allow it to be really a good, “how-to” for making a bowl of matcha.

For something like what the stated goal of the Handbook is, it should consist of sections like this (maybe up to about 20 steps for each section) with one or two short paragraphs between each one, and some headers to make different sections easy to read.

What it mostly looks like, is large blocks of exposition with long paragraphs, with a few different interspersed sections.

I will say, that reading the Handbook, is far more enjoyable as it’s currently written.  But something which is something that people end up reading, is not a, “how to” so much as a, “all about.”

The handbook, as it currently stands, is actually not serving really any genuine documentation function, because it ends up with confusing about 4 different functions, in a single document.

The thing is, the response to, “um, actually things are kind of not that helpful,” is usually, “yes they are, shut up.”

If you manage to get beyond that, you get to, “Just fix it yourself.”

Well, I have in a lot of case have been fixing it myself.  But because of the community, it doesn’t go to the community, but rather to my own space, which is publicly available.  Partially because the best I tend to manage is to document a given process, and when working with something like that, and you start to change the different parts like that, you better have a plan to handle the whole thing eventually, and welcome people to contribute to it.

By welcoming people to contribute, it means you don’t just say, “you are welcome to contribute,” but rather, “thank you for your feedback, and we’ll be looking into it.”

Technical Issues

These are not really problems with the technology itself, but ways that the technology tends to be difficult for many people to actually use.

A lot of this comes down to some stuff that I actually really like about this.

Gentoo doesn’t really (well it sort of does) have “releases” per se.  What it does have that comes close to being, “releases” like most other distributions is, “profiles,” and in a way this is rather similar to releases.

That said, I have 42 available profiles, on this machine which break into 4 or 5 different sets (depending on how you count).  So in some ways some of those are duplicates, triplicates, quadruplets.  These basically are a set of different, “rules” for your system, and that’s a good way to consider how they work.

The main Gentoo ones are 2 different sets which are called 17.0 and 17.1 (and other numbers previously), which get updated from time to time.

I have worked on some systems for long enough, that I’ve updated the profile at least once on most, and twice on some.  Updating from a profile which no longer exists, to a new one can be very tricky.  Part of why I like to keep to a relatively recent version, and since it usually is capable to do at incremental steps a lot easier than skipping them, then it’s worth doing from time to time.

This gets a bit into why most people don’t really want to use a system like Gentoo.

If I’m updating regularly (anything longer than about 10 days can be a problem) I don’t find that doing the updates is really that big of a deal.

But, most packages are installed from source (at least it usually is an option, and the default) so a package which can take 5 minutes to install on other binary based systems, can take an hour, maybe even longer on older hardware.

This actually is a bit of an advantage on that older hardware, as Gentoo actually (from experience) is able to support a wide range of hardware that other distributions are not able to.  At least not while sticking with the latest versions of them.  I have recently installed on a Panasonic Toughbook CF-47, and it runs reasonably well.  It’s certainly not a, “modern computer” but it’s a decent computer.

But, I have stuff that ends up running for days on that computer.  Because it just takes that long to run.  I don’t much mind, because it’s a low use machine, and I really wanted it as a, “distraction free writing/editing” computer.

So, a big part of the problem is that some things (because it compiles stuff) take a long time.

But, also there is another problem, that because of a lack of “releases” it can run into a problem that certain things just don’t work well…

Sometimes when you are doing updates, you find that they just don’t work.  At least not initially.

Occasionally, I have found that I have to uninstall software, in order to install other software because of conflicts.

I actually, enjoy dealing with these sorts of problems, most of the time.  They are the kinds of problems that are fun to work on for us.  But, they aren’t for most people.

So, the combination of technical issues, with the community issues, I tend to not feel that I would recommend it, unless I’m also willing to work very closely with a person to keep things the way they want them.

And sometimes I know that no matter what, I’m going to be working closely with a person, if I want them to have a reasonably up to date system.  I’d rather they have a, “not as updated as I would like” Gentoo system, than a Windows, or macOS system that is just as much out of date.

Posted in Uncategorized | Comments closed

Our thoughts on Mastodon

Mastodon really seemed like a great thing, that the creator (Eugen) was maybe a little unaware of implications and all of that, but really did seem to have a good sense of what the “right” thing to do probably is as far as social media is concerned.

I’m not sure that he has a good understanding at all.  I sure hope that he does not, because despite the efforts of many to find better ways to handle a lot of the problems that exist with it, for quite some time (I think I’ve been watching for about 18 months, and by watching, been actively involved on the platform).

Anyway, he likes to say that it is, “Twitter, with longer posts and no Nazis.”

Is it?

Twitter like?

Yes, very much so, for one thing, a big part of what makes twitter, twitter is that the posts are relatively short.  The started out at 140 characters, and I believe that right from the beginning people complained that they didn’t really work that well for them.

140 characters is really short, and it takes really condensing something a lot to get it down to that.  A lot of what I enjoyed when it was at that length, was to find ways to make those 140 characters really work.

So it does have short posts, but they are longer, they are 500 characters by default (well limit), and while it can be changed, it’s not really that easy to do so.

Even at 500 characters a lot of what makes Twitter the space it is, kind of still exists.  You can express a lot more in 500 characters, than 140.  Well, sort of.  I don’t really think that for the most part you can…

Longer Posts

This is an indication that it is, “better” and yeah, I kind of like the longer posts better, but…  Um…  Yeah, are you really expressing stuff better in that 3.6 times the space?  I don’t think it makes a whole lot of difference really.  For the most part, it is expressing the same stuff, with more words, and somewhat more chance to be misunderstood.

The *idea* of what can be expressed is basically not that much different.  You can basically express one idea.  And the idea most people interpret things as, is, “only one idea” and means that any kind of subtlety easily gets lost.

No Nazis

Well, here we very much differ.  There *are* nazis.  In fact, there have been a lot of migrations from Twitter, YouTube, Facebook, Tumblr, etcetera, because of crack downs on certain types of things, including far right attitudes.

There are whole instances which exist which are created *to* promote far right attitudes.  And honestly, the tools we have to handle that are probably *worse* than what Twitter does, because of the nature of it.

So…  How does this really mean that Mastodon really is?

Mastodon Feel?

Well here’s the thing, there are basically three different types of people that can “find a space” on Mastodon, the people who have a small community and want to stay within it.  And those who want to move across communities, who have no interest in speaking between those communities.  And those who want to move across communities, and have a tough skin.

If you dare say anything where you don’t *agree* with what’s being said, you are very much saying the exact opposite of what the person is saying.

There is no sense of anything other than echo chambers there.

There *are* places where people get along decently.  But a big thing is, that a lot of the conflict runs between and through the whole space.  The idea that you, “should” call out people who are not your extreme view, honestly…  It’s the way things are.  Anyone I’ve seen who have tried to be decent and find ways to fix the extreme polarization either just giving up on saying anything except meaningless stuff, and responding to the people who haven’t given up yet…  Or they end up leaving.

It’s only gotten worse there…  And we have officially left, though I don’t believe we are totally gone yet.  And of course, a big problem is, “it’s there forever”…

Posted in Uncategorized | Comments closed

Game Development Thoughts (1 of however many)

OK, it seems like it was a few weeks ago that I was talking with a friend over on Deviant Art, and was talking about the fact that I’m feeling that I need to work on some game development stuff, and need to figure out what I need to do to do that.

The first thing for me about this was to look in terms of which games I have personally found more “successful” from my perspective.

I am very much a person who uses words a lot, so I looked into the ways that I could do that, and played with some stuff with RenPy which is a visual novel platform, engine, whatever which I really enjoy “playing” visual novels, but for whatever reason I felt that I was running into some pretty significant issues with that, which I really didn’t feel I could resolve…

A big thing that I do remember, is I had a lot of trouble with probably two things…

Without visuals these end up being, “very strange” and I really didn’t feel that I could produce the visuals that I wanted for them (even if I got the story written).

The way that writing for them, the text just didn’t work that well for me, as it is written as code.  This is probably a reasonable example (from the site):

define s = Character('Sylvie', color="#c8ffc8")
define m = Character('Me', color="#c8c8ff")

label start:

    s "Hi there! How was class?"

    m "Good..."

    "I can't bring myself to admit that it all went in one ear and out the other."

    s "Are you going home now? Wanna walk back with me?"

    m "Sure!"

I’m not sure how well this ends up formatting… But this is kind of what seems to be a significant part of how this ends up working in actual practice.

So, I gave up on that, and I guess another factor, (and it could well not have remained a factor if other things didn’t really end up being unpleasant) is that the development and all of that was kind of not very nice place for talking about what is going on with your game, and getting help.

So, someone mentioned Twine and it is a platform for writing “interactive fiction”.  And asked about how to handle stuff around media, and making it work without having to go through extra steps, and I probably have a solution there which I could get to work, if I were to go there.

I found the code tended to work better for me:

:: Passage Name

[[Go to the cellar->Cellar]] is a link that goes to a passage named "Cellar".
[[Parachuting<-Jump]] is a link that goes to a passage named "Parachuting".
[[Down the hatch]] is a link that goes to a passage named "Down the hatch".

Sort of made a lot more sense to me, and this isn’t just some dialogue, but actually includes some code…

Also one other major factor is that for the most part, whitespace is not important.  Though there are cases where a mistake in whitespace has been a problem.

And probably for me, a major factor why I now have 3 different projects that I’ve put a lot of effort into, has been that the development community has always been, “Hmmm… that’s weird, can you let me know more about the details”.

But still.  While I’d say that always has appealed to me, I have spent hours working on stuff like that, and felt it was basically, “nothing”.

So I had done a “game jam” on which I created a game based on a tutorial for Godot.  I wanted to work in Godot for a number of reasons, and the “Dodge the Creeps Tutorial” showed up.  I think from the time I started working on it, I probably took about 36 hours to get a game working well enough to be OK with sharing it.  It was more like 4 hours of actual coding/debugging and possibly a good deal less than that, but a big problem came up which was that I was using a version which wasn’t going to work with the code, and I spent a good deal of time trying to get it to work for me.

That simple Godot game was probably the favourite game that I worked on.  There really isn’t any “story” that I need to go into to make it, “fun” and it was just about trying to figure out where I wanted to go with the game in terms of how to modify it.

So, that discussion lead to thinking about how to do something like that.

I was thinking about the kinds of games that sort of fell into being able to create something which is playable in a relatively short time, but might end up being a game that could have multiple releases that actually are improving the game, not just fixing bugs which are found with it.

So, that game, as it starts, doesn’t really develop over time.  And in a lot of ways that’s something that would need to happen for a game to be long-term enjoyable for people.

So I was thinking of games like Asteroids, Pong, Apple Panic, Loderunner, Donkey Kong, and a lot of different games like that.  Most of them are some form of a 2D game, and these are “old” games that people are still playing.

So, without really going into it, I decided something like this just made sense for the next game project…  But I didn’t go anywhere with it.  Then someone in a game development chat, was talking about game design, and game play, and I started to think more, and realized that I probably need to look in terms of that.

And that started me thinking about how game design, and game play sort of work.  And I need to seriously go through trying to figure this out.

To me, there are elements of, “world” and “character”.  Some games there isn’t much sense of character, as it’s like a “solitaire” type game like most of the card solitaire games, or mahjong.

There is just a “world” which has what you have, and you just kind of “work” and the character element is really downplayed.

Then most games have more of a character involved.  Whether it is your spaceship and enemies in something like Asteroids, or all the way up to some of the 3D multiplayer games.

And of course there is how much or how little “story” there is in your game.


  • World
  • Characters
  • Story
  • Gameplay

Probably a good place to think about these things.

So, this was probably a good sort of thinking about things and starting to look where I want to think about how to move forward with this.

For now, I think I’m going to leave this post here.  I need to think a lot more about how these kind of come together.

Posted in Game Development | Tagged , , , , | Comments closed

The Myth of Data Security

There are people who have talked to me recently about, “it is scary what you can do with data” and I have stated that by deleting their messages after 7 days protects them.

This is at best misguided, and I’m not saying much about the people who are publicly making such statements as part of journalism, because I don’t believe they are saying what they don’t believe, or at least don’t believe well enough to make it worth saying.

Here is what someone who claims to know about the risk of what can “be done with data” will know that any of the following things will cause it to be indexed:

  • Being opened on any of these devices:
    • Apple
    • Google
    • Microsoft
    • SuperMicro
    • Huawei
  • Being posted publicly
  • Being shared publicly after having been posted privately

Based on this information, it seems that there simply isn’t likely that the “data” portion is protected.  The being posted publicly, or being shared publicly after having been shared privately means not only is it indexed, but it is also being archived (often publicly).

This information which I think is pretty clear to say that you can’t protect your data (end to end cryptography is the best that you can achieve, but I’d question whether it isn’t at least indexed in the vast majority of cases (ie. it gets indexed by Apple, Google, Microsoft, SuperMicro, or Huawei) is practically impossible, though there is a possibility it wouldn’t be indexed by all of these companies, but the chances it’s not indexed by at least one of them are practically impossible.

So, tech journalists who are talking about whether or not doing certain things would be helpful, sure, they believe that, but either because they aren’t really talking about the risks of the “data” but the risk that a human will find it, and act on it, or they are really just hoping that simply reducing the active access can reduce those risks.

Posted in Computer Security, Data Security | Comments closed

Email List…

I was checking some stuff out on MailChimp, and I notice a user I never noticed before had unsubscribed.  I was trying to delete the account, and I couldn’t, and then I see, “Unsubscribe reason: Spammy content”.

This person subscribed to this newsletter on September 3rd, and I posted *nothing* which they wouldn’t have been able to see at that time, so their subscribe *knew* what they were getting.  So, I guess that

Literally subscribed for the *sole* purpose to unsubscribe with that claim…

So…  I guess they may just want some *genuine* spam…

Sorry, feeling a smidge vindictive, as they decided they wanted to do that…

Posted in Uncategorized | Comments closed

Mastodon Setup (hopefully final update)

Today I finally found out how to generate log files.  They are “less than ideal” but they are good enough that I figured out what the main problem was and it was a typing mistake.  I had (and I’m not sure how this happened):


When what it should have been was:


This was setup as a security feature, and I think at one point I made changes to that section of code thinking that the recommended security that was there, could end up getting things fixed.

From what I can tell, things are working “as expected”.  Well, mostly, some things aren’t working quite how I would like, but I think it is all well enough.

So, if you want, you can go over and join the Mastodon instance.


Posted in Business News, FLOSS, Linux, Product News, Site News, Web Development | Tagged , , , , , , , , | Comments closed

Mastodon Setup further updates…

I haven’t seen a whole lot of improvement today, but I did see that I ended up with some toots coming in which are closer to when things were happening on the system, but it seems that for the most part this really isn’t working all that well.  It’s OK.  I’m kind of getting frustrated, but I guess I can live with how things are for now.

One thing, someone was talking about it on one of the other mastodon instances, and I saw that I just am looking “very generic” and I didn’t really like that so I did a quick bit of work to try to get something together that looks at least different, even if it’s not really all that fancy…

"Mastodon on Open Psychology" with a simple background with green hills and clouds

This is the “thumbnail” which I created for the mastodon instance.

It certainly isn’t generic, so I think that’s a big plus.  But it’s also not all that nice.  I mean I do like what I ended up with, considering the amount of effort that I put into it, but it’s still not something that I’d say should be sitting around for long like this.

I did think that I liked the way it turned out when I took the text off so I also created a version like that:

green hills with clouds

This is what it looks like when I take the text off.

I actually think this ended up turning out not too badly at all.  The nice thing with working in a digital format is that if I do the layers thing correctly, I can usually get stuff to look fairly decent because I don’t have to worry about how each element works with the rest, until I start to get to that level of work with it…

Posted in Uncategorized | Comments closed

Mastodon Setup – More information

Last night (about 23 hours ago apparently) I shared about setting up a Mastodon instance, and that things were kind of working but not really.

I shared that is open for registrations, and that people would be able to sign up there (at least for the time being).

And I hoped that people signing up, would help with getting things worked out.


No one has signed up, and so far I don’t seem to have much improvement…

But on the good news front, I decided to fix (or at least look at) the IPv6 setup, and maybe that has improved stuff.  The setup was clearly broken.

Which probably means that it’s broken here too.

I’m not quite sure that it’s “fixed” there, but at least I can connect out, and I had been able to connect in a way that actually was seeing connections.

But I’m not entirely sure that the problem there has actually been fixed.

Some good news.  I’ve had a couple new posts that look like they are from more recently than the previous most recent posts, but still…

They are still older than the oldest post on the server itself.

I checked to see if I could find any logs which might give me more information than what shows up in the Sidekiq log that I can get access to online.

I couldn’t find anything more.


Some of it is working…

It’s coming, and I’m hoping that the recurring jobs which haven’t been run yet, might actually help some of that, and that the plugging away at it might actually help too.

So, I don’t really know.

I think that adding a dozen or so follows seems to be helpful to some extent.

Still.  More people there *might* be a helpful thing.  And I’m still trying to figure out if anyone can help with any of this now or not.

Posted in Business News, Computer Support, Linux, Product News, Site News, Virtual Machines, Web Development | Tagged , , , , , , , , , , , , , , , , | Comments closed