The time now is Fri 17 Nov 2017, 17:14
All times are UTC - 4
Joined: 16 Sep 2009
|Posted: Tue 12 Sep 2017, 13:02 Post subject:
Subject description: We can auto-generate the online documentation
Suggestion: Generating standardised docs by script for each [official or major] release.
- ensure every woof build can generate its own docs
- give each official release its own documentation space online
- use PmWiki (or OddMuse, similar) for main site AND for the Wiki
- standardised wiki and doc pages for each release, nicely organised online
- only ONE location for main site, releases notes, handbook, wiki, bug tracking, forum (iframe this one in)
- create shell scripts to run after a good Woof build:
--- auto generate PMWiki pages (grab templates, replace vars, done)
--- build whole docs package for that release (create the file structure we need online)
--- install the pages online to puppylinux.org (ftp them onine)
--- build a PET so people can have the Wiki locally to work on (etc)
- a github repo for the generated docs .. a branch for each release/puplet, main branch containing the templates from which the real docs are generated
We can achieve the above (fairly) easily, by learning (even borrowing/forking) from
work from others...
CRUX Linux (and Arch Linux) produce better docs, and theirs are easier to maintain:
- their docs are auto-generarated for each build/release
- standardised docs and release notes for each official release
- central Wiki, one place with all major information
- good, long pages with lots of reproducible code examples
Puppys docs are hard to maintain:
- docs manually created for each release, no specific format or location
- sporadic, terse (even cryptic), sparse, scattered around many sites
- the wiki is outdated, MANY broken links, no structure at all
- wiki not organised by release .. pet are listed all over the place only little notes as to which Pup they might be for
- no standardised formats for any releases at all
The poor guys who run around trying to keep our Wikis and docs (at various random
places) up to date are legends in my book.. A totally painful, and probably thankless task..
We need to make life easier for them, reduce their workload and STANDARDISE our
docs with each official release...Even for each Puplet release, bugfix release, RC
(release candidate) and so on ...
How to do it better:
If the scripts to build the documentation are included in Woof, then we can auto-build
ever improving docs, specific to the Puppy built, with standardised pages, layouts, etc.
Each time a Puppy is woof-built, its (standardised) docs should be generated, ready to
drop into the right location on puppylinux.org...
The home page, Wiki (and any other pages that need to be updated to include info about
the latest release) could be auto-generated too .. They would simply replace the old ones..
CRUX Linux 3.3 has an excellent Handbook.
But in fact, it is *mostly* the same as the CRUX Linux 3.2 Handbook.
.. and the CRUX Linux 2.7 Handbook
Their Wiki get updated as they update to a new release, they dont keep separate Wikis
for each release.
(We manually update docs and stuff ad-hoc all the time at many different locations..)
The CRUX devs simply auto-generate PmWiki pages for their main site, for their Handbooks,
Release Notes, and most other docs, whenever they do a new release.
Less work, less repetition, better docs 'coverage', nicer docs, one central location, using
only PmWiki (which is a flat file, lightweight, PHP based Wiki, with Markdown support!)
Adding the markdown plugin to PmWiki means our docs could be generated for PmWiki,
and for GitHub at the same time!
The CRUX website is nearly all one script (PmWiki), and organised like so:
https://crux.nu/Main/ <-- their main site (a PmWiki site, red theme)
https://crux.nu/Wiki/ <-- their Wiki (the same PmWiki site, but with a blue theme)
https://crux.nu/Wiki/HomePage <-- small but effective .. covers basics of most common user tasks.. not much version specific info in there..
https://crux.nu/Main/Development <-- just a page of the main (red) site
https://crux.nu/portdb/ <-- just a page with a table, on the main (red) site
https://crux.nu/bugs/ <-- not a PmWiki page, powered by http://www.flyspray.org/
That is their only site... all on one domain .. Main site, wiki, portdb (users repo list) all in one script.. Then flyspray for bugtracking..
Simpler than ours, better than ours..
And now their Documentation:
If each official Puppy release had its own, specific Wiki and Manual pages, links to them could be auto-generated too.
We need one central site, with release notes and handbooks that are standardised, versioned and automatically
generated with each release.
We could power our main site, Wiki and contrib-repo database all on the same site, quite easy to auto-update
as new releases come out.
We could have a bug tracker (flyspray does look nice! .. and Fossil) at the same place as our main site and Wiki..
Puppy could simply have a Bugs info page, with links to GitHub Issues,
and some more to GitHub Project, Roadmap page, Forum, etc.
We should copy the excellent file structure of CRUX to ensure every release gets it own documentation space,
with info specific that that puppy (repo names, pkg names, version numbers, etc)...
Akita Linux, VLC-GTK, Pup Search, Pup File Search
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum
Powered by phpBB © 2001, 2005 phpBB Group