Better Documentation
Posted: Tue 12 Sep 2017, 17:02
Suggestion: Generating standardised docs by script for each [official or major] release.
In short:
- 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...
More Info:
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
- etc
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:
Release Notes:
https://crux.nu/Main/ReleaseNotes3-3
https://crux.nu/Main/ReleaseNotes3-2
...
https://crux.nu/Main/ReleaseNotes2-6
Their handbooks:
https://crux.nu/Main/Handbook3-3
https://crux.nu/Main/Handbook3-2
https://crux.nu/Main/Handbook3-1
...
https://crux.nu/Main/Handbook2-6
If each official Puppy release had its own, specific Wiki and Manual pages, links to them could be auto-generated too.
http://wiki.puppylinux.org/Releases/$DI ... N/Homepage
http://wiki.puppylinux.org/Releases/$DI ... ION/Manual
...etc
Conclusion:
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)...
In short:
- 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...
More Info:
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
- etc
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:
Release Notes:
https://crux.nu/Main/ReleaseNotes3-3
https://crux.nu/Main/ReleaseNotes3-2
...
https://crux.nu/Main/ReleaseNotes2-6
Their handbooks:
https://crux.nu/Main/Handbook3-3
https://crux.nu/Main/Handbook3-2
https://crux.nu/Main/Handbook3-1
...
https://crux.nu/Main/Handbook2-6
If each official Puppy release had its own, specific Wiki and Manual pages, links to them could be auto-generated too.
http://wiki.puppylinux.org/Releases/$DI ... N/Homepage
http://wiki.puppylinux.org/Releases/$DI ... ION/Manual
...etc
Conclusion:
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)...