Puppy Linux Discussion Forum Forum Index Puppy Linux Discussion Forum
Puppy HOME page : puppylinux.com
"THE" alternative forum : puppylinux.info
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

The time now is Sun 17 Dec 2017, 10:09
All times are UTC - 4
 Forum index » Taking the Puppy out for a walk » Suggestions
Better Documentation
Moderators: Flash, Ian, JohnMurga
Post new topic   Reply to topic View previous topic :: View next topic
Page 1 of 1 [1 Post]  
Author Message
sc0ttman


Joined: 16 Sep 2009
Posts: 2548
Location: UK

PostPosted: Tue 12 Sep 2017, 13:02    Post subject:  Better Documentation
Subject description: We can auto-generate the online documentation
 

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/$DISTRO_VERSION/Homepage
http://wiki.puppylinux.org/Releases/$DISTRO_VERSION/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)...

_________________
Akita Linux, VLC-GTK, Pup Search, Pup File Search
Back to top
View user's profile Send private message 
Display posts from previous:   Sort by:   
Page 1 of 1 [1 Post]  
Post new topic   Reply to topic View previous topic :: View next topic
 Forum index » Taking the Puppy out for a walk » Suggestions
Jump to:  

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
[ Time: 0.0328s ][ Queries: 14 (0.0042s) ][ GZIP on ]