Tim here with a couple ideas from maintaining my own website.
It sounds like all the content is fairly static (not dynamically
accepting comments, or interactively rendering things based on
user-input) so it sounds like a good use-case for any the zillion
"Static Site Generators" ("SSG") out there. I happen to use Nikola,
but know a lot of folks like Hugo or Jekyll. Most folks author
content in Markdown (though I prefer to code in raw HTML as I've
been using that since the mid 90s). Then, the SSG can take all
those input files, churn through them, and spit out a website with
proper interlinking, indexes, RSS feeds, tags, timestamps, etc.
The other thing to consider is where you want your canonical
page-content to reside: in your Github repo(s) or in your blog.
If you prefer to keep the canonical description in Github pages,
you can create an index-page of links to those repos and their
read-me files. Alternatively, you can keep your blog as the canonical
documentation source (whether one page for everything or one page
per project), and then copy those documents into your Github repos
as part of the deployment process.
Both work for me. For my own stuff, anything I publish to Github,
I keep the documentation alongside it there, and just reference it
with a link from my blog if needed.
-tim
On 2023-09-06 13:43, Linux for blind general discussion wrote:
> I would like my website to conveniently present my software work. I.E.
> The reader clicks on software, where they can see all my applications,
> filter them by platform and so on. However, I can't decide how to
> present the individual programs.
>
> One approach is to simply use the readmes from GitHub. I'm usually
> pretty consistent when writing these, each important readme has to
> contain an introduction (what's the program about), build instructions,
> usage instructions, additional documentation (if necessary),
> acknowledgements and license information.
>
> I guess that quite works for a website in terms of size, it also doesn't
> introduce any burden on writing and maintaining. However, when thinking
> about this solution, I can't get rid of feeling it's sort of cheap. Like
> yes, the user gets thorough information, but when they click the Github
> link, they will see exactly the same text and the first idea will be
> "Hey, this person didn't really put a lot of effort into the site".
> Plus, the usual scheme of readmes is something so much associated with
> GitHub I'm afraid it would be sort of weird to see it as a webpage.
>
> Another approach is to simply write a new page for each program. This
> quite works for bigger things, where you need to explain the concepts,
> reasoning behind them, you may want to link other resources etc. But,
> what about the smaller-ones, like:
> https://github.com/RastislavKish/mtg
>
> As helpful as this little cute utility is, it takes like three sentences
> to describe, and what then? You end up with a blank page with one or two
> lines of text on the top. That doesn't sound particularly convincing,
> either.
>
> as a user, how would you expect a website to present you a software
> collection? Or as a developer, if you have multiple bigger / smaller
> projects going on, how do you write about them under one roof?
>
>
> Best regards
>
>
> Rastislav
>
>
>
> _______________________________________________
> Blinux-list mailing list
> Blinux-list@xxxxxxxxxx
> https://listman.redhat.com/mailman/listinfo/blinux-list
>
_______________________________________________
Blinux-list mailing list
Blinux-list@xxxxxxxxxx
https://listman.redhat.com/mailman/listinfo/blinux-list