[Xastir] Poll: how do you like your documentation served up?

[Tom Russo]

On Sun, Jan 04, 2026 at 08:49:32PM +1100, we recorded a bogon-computron collision of the <edodd at billiau.net> flavor, containing:
> On Sat, 3 Jan 2026 14:01:36 -0700
> Tom Russo <russo at bogodyn.org> wrote:
> 
> > I have been hard at work trying to build out the Github wiki to be a
> > more readable and up-to-date set of Xastir documentation, since
> > xastir.org has been dicey of late, and the in-source READMEs are very
> > out of date.
> > 
> > It's coming along, but it is still a work in progress, but I am keen
> > to have feedback and suggestions.  I'm also keen to have help.
> > 
> > Please go to https://github.com/Xastir/Xastir/wiki and take a look.  
> > Constructive criticism very welcome.
> 
> 
> I've written a few bits.

Saw that.

I also saw that you added "libwebp" to the dependencies.  That's one that
often gets left out, as it's mostly something that other packages depend
on, not something that Xastir uses itself.  Thanks for adding it.

But fact webp is a dependency of GraphicsMagick, not a direct dependency of
Xastir.  GraphicsMagick has a lot of other dependencies and we don't list them 
all.  Are you sure we need to in our install document?

> The old wiki didn't seem to have a clear backbone, and multiple
> categories appeared under the "HowTo" section, ranging from Linux tips
> through how to set up one's radio hardware through to clearly Xastir
> topics like maps and dbfawk.

I agree.  The old wiki was just a collection of people's input on the 
topic, all done in different styles by different folks, and stuffed into
whatever pigeon hole was already there --- hence all manner of stuff showing
up in HowTo.  Many of those pages were just taken out of dialog from the 
mailing list.

> I am in favour of a clear backbone of major topics which are in a
> sidebar for navigation and a full list of other pages.

Yes, the sidebar needs to be more useful than it is.

> There are many pages with abbreviations in their titles. I understand
> most of them, but couldn't identify CS, SB and WMS.

AH.

SB is "Smart Beaconing", WMS is "Web Map Service", "CS" is Coordinate System.

The page names are just the file names, I have tried hard to use intelligible
text wherever those pages are linked from text instead of the page name.  
And each of those pages defines the abbreviation it uses.  But I see what you 
mean, it makes the default sidebar look stupid.  And since I've written
the wiki so far as many, many small files instead of a few huge ones,
that sidebar isn't helpful at all.

The default Github wiki style puts the page names in the sidebar on the right, 
which isn't helpful.  I was writing everything from the point of view of the 
user reading the text in the main body, and have been ignoring the sidebar
as basically useless (it is alphabetical, includes every single page, and
it only shows the first few pages (alphabetically) unless you click the button
"Show X more pages" at the bottom.

I think the right thing to do is to make a custom side bar that actually
works for us.

There's a button at the right, "Custom Sidebar" that is just another markdown 
document.  If we wrote something there that made more sense than Github's then
it would appear there.

https://docs.github.com/en/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki

This tool might even be useful:
https://docs.github.com/en/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki

As for abbreviations in the page names, I'm thinking that as long as the 
file name isn't used for *ANYTHING* other than linking to it shouldn't 
matter.  The real problem here is that the sidebar shows the filenames, which
are not the real message.  A well-crafted sidebar would be a good addition.

Do you want to have a crack at it?  If you don't have time, maybe this is
what I'll work on next.

-- 
Tom Russo    KM5VY
Tijeras, NM  

 echo "prpv_a'rfg_cnf_har_cvcr" | sed -e 's/_/ /g' | tr [a-m][n-z] [n-z][a-m]