Documentation, The Forum and the Wikki pages.

[cobaka]

Woof to all!

After following a thread about the failure of Lick to install/run Puppy Linux to a PC for 56 postings I began to think about documentation.
The Wiki has a lengthy index <Category Installation> on this topic. There I see a lot of information about installation. A lot!
Link: https://wikka.puppylinux.com/CategoryInstallation

There are other pages dealing with installation too, but these are on the forum:

Link: https://www.forum.puppylinux.com/viewtopic.php?t=5275
Link: https://www.forum.puppylinux.com/viewtopic.php?t=5294

Glancing at the Wiki pages I see an enormous amount of work has already gone into documentation. There are 58 links - yes links - dealing with the topic of installation. Topics include BIOS, BOOTFLASH, BOOTLOADERS ... Windows Installers to WOOFY. (What is "woofy"?) It's a long list of categories.

Here is the link to Windows installers: https://oldforum.puppylinux.com/viewtopic.php?t=61404
This points (or links to) the "old forum". It mentions Lick and gives a Link to download Lick from github:

The link: https://github.com/noryb009/lick/releases/latest

Here is my impression of this cornucopia of info: If you know where you want to go it's possible to get there, but if you don't you may never arrive. It's a bit like the tourist in Ireland who asked the best way to Dublin city. "If you want to go to Dublin", the local said, "I wouldn't start here."

In this case all this work (58 links to many pages of detailed information) comes from the keyboard of 'DarkCity'. Looking at this, my impression is that wherever 'DarkCity' lives his light is rarely dark.

To the person familiar with Linux (even to the superficial degree of familiarity that I have) the pages "Category - Installation" are a gold mine of information. To a person unfamiliar with 'computer-speak' these links are a dark and complex cave-system full of obscure words.

On the forum the section "getting started and system requirements" (by Rockedge) provides a different style of info about the installation procedure. Again, looking at the detail on just a single page suggests Rockedge also works late. Or maybe, just maybe, he rises early.

Some months ago I looked at the task of keeping the Wiki up-to date. Then - as circumstances happened - the Wiki would not allow me log in and I put the idea of contributing aside. I had two principal observations about documenting Puppy Linux.

The first comes from ISO 9000. Good documentation practice suggests a single 'master document' should exist - not duplicates.
The second comes from that idea of a 'single master': Without a map to navigate 'the system' - that is the documentation in both the forum and the wiki - maintaining a 'single master' is impossible.

After that there is the problem of 'cross transfer of knowledge'. For Rockedge (to use his name as an example) to write a document without duplicating the excellent work of DarkCity he [Rockedge] must be aware of what DarkCity has done. I don't think I need to expand this point further - the difficulty is obvious.

Finally, to return to the starting point that began with an installation that didn't load it would be most useful if problems that are described on the forum could be solved by giving a link to some existing page on the forum or the Wiki. Then, if that was possible, we might think that the documentation for Puppy Linux was well done.

When I think about the individual effort put into creating the various versions of Puppy Linux, and after that, how I use Puppy every day for every sort of computing work I'm astonished that such a functional system has been assembled by .... well, by unpaid enthusiasts. Microsoft, hang your head in shame! Puppy Linux is an excellent OS. Puppy Linux deserves first-class documentation. How can that be done? Hmmm?

Comments about documentation are invited.

Cobaka

[Feek]

I think the project "getting started and system requirements" is very useful (not only) for new users.
It briefly describes the basic things.

If it is a user who does not know computer language, knows nothing about computers or Linux, then he will have to be patient and gradually discover everything.
As for practical experience with using Puppy and more complex tasks, the user gets it himself step by step by trying things, searching for information on the forum (I remember my beginnings with Puppy).
If necessary, he can submit a question to the forum.

E.g. in my opinion, the Fatdog documentation is very well processed and regularly updated.
But Fatdog is one operating system unlike Puppy, where we see many versions based on different distributions, derivatives, older versions.
So I don't know if it would be possible to build a universal detailed documentation valid for all puppies.

[cobaka]

G'day @Freek

So I don't know if it would be possible to build a universal detailed documentation valid for all puppies.

Good point. I thought about the diversity among the different kennels. What does diversity bring? Why is it useful to have Xenial, uPupBB, Stretch, Tahr and all the other puppies? My answer: An OS that is sufficiently "open" to new development (as distinct from Microsoft - a closed system) brings a continually developing pool of expertise. Our present personal computing world grew from the interest of individuals in computer groups spread (mainly) across USA. Some turned this "interest" into a business. Remember Gary Kildall and "control program/microprocessor"? Microsoft came from that environment. Thus diversity has advantages.

For us Puppians documenting this diversity is a problem, as you said. Perhaps Augustine knew something when he wrote: “In essentials, unity; in non-essentials, liberty; in all things, charity.” Liberty brings freedom, but liberty has a cost. Don't believe me? Ask the 625,000 men who died in the civil war, (1861 .. 65). Or, before that, men like William Penn who crossed the Atlantic to find liberty. But that's not the topic in this thread. We are discussing documentation.

The problem at the next level down is for a single individual (or even a small group) to acquire and organise the collective knowledge to describe the various puppy kennels. Getting, organising and publishing that info may be a task not smaller than creating a puppy kennel. That's why the topic "documentation" is important. That's why the wiki is important.

Finally, Puppy Linux needs a mechanism to protect this public knowledge (and Puppy itself) from theft. Perhaps it already has that. I just don't know. I'm thinking (of course) about a "free software" license such as GNU. If Puppy became business then it would no longer be the bold, fearless puppy that roamed free around Barry's Kauler's house in Western Australia. A business would fear the "bad critters" that lurk at the bottom of Barry's garden. A business would invoke the laws of copyright & co to protect from "nasty critters". Software published by a business would cease to be puppy. Woof!

Cobaka

[williwaw]

Puppy Linux deserves first-class documentation. How can that be done? Hmmm?

Have you seen? viewtopic.php?t=4781

One thought I had was to see if the original wikka markup could be easily converted to a more universal markup.

Rock has proposed mediawiki. Presumably to host the converted wiki on this server. I thought if there was a way to convert the original wikka markup to Markdown, then github could possibly be considered for hosting.

Another aspect of doing a conversion that might be worth considering, is to organize the documentation in an index modeled after something like...
https://docs.freebsd.org/doc/8.4-RELEAS ... /handbook/

[Clarity]

... For us Puppians documenting this diversity is a problem. ...

Yes, this presents just one of the problems faced in this forum, since there are 6 different PUP/DOG methods a forum distro is produced for consumption by any user, new or experienced. Everything from WoofCE, WoofQ, and other methods used for building which translates to some details that would have a sligthly different structural need and use; thusly impacting documentation.

I have been wondering, too, how to best organized the documentation "food dishes" for each of the diversities to make it easy for users to grasp.

In my years, production was based upon documentation. But, I AM AWARE, that often times, great developers are not the best documenters even though they know there product well. And today, the world exist in a multimedia fashion vs the 'print' media of the past.

As I have reviewed the landscape of today's world, THIS has cause me a re-thinking of what are the best methods to present information even as I know of each type of diversity in Puppyland. Audio offers, video offers, print offers in the various generation tools, flow-charts, etc. ???

Maybe, it will evolve into a kind of manner of presenting information that is both targeted and easily consumed via some simple navigations.

I think this is one aspect that many/few are wrestling with.

[Phoenix]

I find it problematic that not anyone can create a account for the wikki. Worst case an editor will have to revert bad changes. I think a combination of texts and videos are the most effective way to get it across.

We can somewhat standardize puppy, the init and its related systems are somewhat universal, not withstanding changing pup_rw to something else.

[rockedge]

I find it problematic that not anyone can create a account for the wikki.

Only new registration is disabled at this time due to excessive spam attacks by bots and humans through the registration system. The current wiki software we are using is end of life and the project is ended so I am looking at what it takes to convert what we have into a new database or file system on new wiki software which will also need to be installed, configured on the host server.

I don't have the time right now to 100% dedicate to the cause. If one is registered you can log in and continue to work on the wiki. But until a better anti spam mechanism is found or new software installed, it will remain closed to new registration unless coordinated with me so I can turn it on for that moment and again shut off registration as soon as possible

[cobaka]

Hello @rockedge and anyone else silly enough to read this:

Questions about editing the Wiki.

(1) On another thread the form (i.e. the mark-up code) and future location (i.e. server) of the Wiki is discussed. Thinking about this - if the wiki is moved to another server a different mark-up code may be used there. With that in mind I ask: Will any form of editing the existing wiki page create additional work when the wiki is moved? Is it better to merely assemble text and images on my own PC with a view to incorporating them into the Puppy wiki after it is moved to a new home?
Here is a link to the wiki "categories" page:
https://wikka.puppylinux.com/CategoryCategory
From that page you can see the style guide - the second last item on the list.

(2) Images. Looking at ten typical wiki pages, I see few images. Consider the installation page: https://wikka.puppylinux.com/CategoryInstallation
This is essentially an index page, and used intelligently it has a lot of useful information. A few images here or on sub-pages showing the relationship between the various components used in installing and booting the Operating System would (I think) set out the installation process more clearly. Installation is a topic that creates many postings on the forum. A clear explanation of that topic with diagrams would reduce the number of questions & postings, I think.

(3) This leads immediately to another point. Storage of images. In the style guide (referred to above) I read:

To insert an image, you have to point to an external link where the image resides, as this wiki does not provide in itself options for image storage.

This, I think is wrong. I don't have to point to anything. The mark-up code in the wiki has to link (or anchor) to the URL of the image. (But I'm just being "smart" really. I know what "point to an external link" means; the pointing just doesn't involve me.)
Where, I ask, are images seen on Wiki pages stored? Is there a single server, or many?

If some-one (any-one) edits a wiki page and the complete wiki is moved to another server the link to every image in the wiki must be changed.
If all the images are stored on the same server, then editing every page may not be a irksome task if the serial editor 'sed' was used. Just a thought. BUT (joy of joys! - a second though now cometh into my mind). If faithful SED was used to modify every page containing an image the process of checking the work may take more time than the coding. (A rather troubling thought.)

The paragraph above takes me back to point #1 - about on-going maintenance of the wiki; this is a convenient place to end this posting.

cobaka.

[rockedge]

@cobaka The wiki is already on the new server. It would be a change in the base wiki software. I am looking into MediaWiki to replace the WikkaWiki package we use now. The Wikka "last man standing" project developer has called it quits and the project has been discontinued.

The version on the puppylinux.com server is the latest one available. The job would be to convert the WikkaWiki pages into MediaWiki pages.

[wiak]

Here is my impression of this cornucopia of info: If you know where you want to go it's possible to get there, but if you don't you may never arrive. It's a bit like the tourist in Ireland who asked the best way to Dublin city. "If you want to go to Dublin", the local said, "I wouldn't start here."

... For us Puppians documenting this diversity is a problem. ...

Yes, this presents just one of the problems faced in this forum, since there are 6 different PUP/DOG methods a forum distro is produced for consumption by any user, new or experienced. Everything from WoofCE, WoofQ, and other methods used for building which translates to some details that would have a sligthly different structural need and use; thusly impacting documentation.

Not only is there a lot of diversity, such that any documentation needs to come in modified forms to cover distro/project differences, but this forum (and wiki) tends to cover all aspects of Linux as and when a user decides to post about them. That is too much, or at least it hides the essentials, which are really to do mainly with how to install, and how to use.

I do believe a wide-ranging wiki is useful (as Arch Linux wiki shows, but probably does better just than this forum could hope to accomplish), but simpler, more specific document (in per-distro/project modified form) is what is really missing in terms of encouraging new users.

As an example of what I mean. Manjaro's user documentation effectively contains the 'Contents' list of what I believe needs fleshed out from Puppy/Dog distribution point of view (see attached). These (alternative version) documents (with much in common with each other) could be maintained as a smaller second Wiki, or simply on a site such as github, where they would be easy to review and update without allowing them to become over-the-top bloated with too much unnecessary information.

Certainly, it is my own intention to eventually produce a shortish document in almost exactly that 'Contents' form for my WeeDogLinux-related work, but I just haven't found time yet (in the over two years now since WDL began).

[wiak]

On an aside from my immediately above post:

I would agree, that for a somewhat higher technical level of documentation, that provided by the FatDog team for their distro is an excellent exemplar (and per usual a lot of information is the same for all the distros we discuss so totally re-inventing all wheels is not necessary):

https://distro.ibiblio.org/fatdog/web/faqs/faq.html

However, best to stick with only the essentials in main user documentation (per previous Manjaro 'Contents' example). Extra distro specific information such as what FatDog's FAQ covers is best provided in a second document I feel.

Large, ever expanding Wikis, unless carefully and regularly moderated (which they rarely are on such a small forum as this one) simply become unwieldy and full of a mix of some relevant and much out-of-date information. Out-dated and often entirely wrong information is very dangerous since it causes a lot of wasted work and confusion and finding correct up-to-date information becomes like searching for a needle in a haystack. I really hate that kind of wiki because my life is too short and I hate wasting so much time reading rubbish.

[cobaka]

Hello all & woof!

Returning to the topic of documentation, based on a recent embarrassing experience.
In short, I installed uPupBB32 using an out-of-date CD I made some years ago. The 'out-of-date' iso file created a problem.
I got some helpful replies - here, on the forum - when I wrote about the failure to find the save-file/folder here.

My mistake wasted other people's time. I decided to check the "official" documentation about installing Puppy Linux.
Maybe, I thought, if the installation note began with an instruction to download the most recent "iso" file from the reference library I might save others from the same mistake.

Looking around I found two places where installation notes are found.
A. This forum: https://www.forum.puppylinux.com/viewforum.php?f=85 and
B. (the Wiki): https://wikka.puppylinux.com/Installati ... edirect=no

So! Two places that describe the process of installation. I intended to edit these to add a note: "only install the latest version, downloaded from ibiblio" (or wherever). The forum pages are (at the moment) only "place-holders" - mostly empty pages for the future. The Wiki pages are full of information that appears to be generated by some form of 'automated process - perhaps grepping' or indexing ... Lots and lots of info, page after page of really good info - but who can wade thru all this treacle and find the info they need? I think a well-informed Puppian may do that - but not a noob - and a noob is certainly the audience that the pages were written for! Hmmm!

My question: Does the Puppy community have a view about the place for 'official documentation' Is this place the forum or the Wiki?

cobaka.

PS Well before this I wrote some general notes about the logic of installing an operating system. These were general notes and applicable equally to Linux, Windows or any OS. At the moment these notes remain on my computer. After thinking about where to post - I put my work aside while good Puppians everywhere resolved the question about the location of Puppy documentation. I'm not even going to enter the discussion about "where to publish" except to say: There must be only one "official" source of info about Puppy. See ISO standard 900x

[williwaw]

There must be only one "official" source of info about Puppy. See ISO standard 900x

Thats reasonable. Perhaps the original should be in some common format, should the documentation need to be restored from a backup to a different location.

[bigpup]

viewforum.php?f=85

These are the subsections of the How To section of the forum.
Click on one and all kinds of topics dealing with the subject of that specific subsection.

The Forum is probably the best place to provide information.

The WIKI is really not being kept updated, does have some info that really is old, and not that good.
Some links are dead.
I am not sure who is really trying to keep it updated or even if someone is.

[wizard]

@cobaka

Go here viewforum.php?f=184

Read these topics:
-Making a CD or USB for your First Boot
-Installing Puppy to a UEFI Internal Drive
-Installing Puppy on an MBR (Legacy) Internal Drive
-Installing To A Bootable USB Drive With A Save File
-Dual Booting With MS Windows

Although these apply to newer Pups, they can be modified or interpreted for any version.

wizard

[cobaka]

Hello all:

Correction:
Earlier in this post (see below) I wrote:

The forum pages are (at the moment) only "place-holders" - mostly empty pages for the future

This is quite incorrect. The pages are full of good info. I saw nothing because my 'viewing window' was set to display only entries submitted over the previous 7 days. Most posting were made earlier than that. That's why I made that (completely incorrect) observation.

cobaka.