##Yaffle's thoughts on documentation...
I've completed converting the existing documentation HTML into markdown. It's available on https://profyaffle.github.io/ and https://tvheadend.readthedocs.org/en/latest/.
Basic structure of pages is now more consistent, as is layout/format. Content varies wildly, from current to rubbish; language is similar, some is clear and some needs re-writing.
The conversion of the webUI-specific (tab) pages seems to be functioning okay as well, so I have write-once, use-many
###Proposed next steps:
- PR CSS changes to tvheadend master to support new help documents.
- PR replacement html files to tvheadend master (converted from user guide). These still have a lot of holes.
- PR removal of dead html files to tvheadend master - those I can't find a use for.
This gives a stable base on which to make further content changes/additions. Current content is replaced with work-in-progress content (warts and all)
- Continue (with help! :) ) to update the User Guide on https://github.com/ProfYaffle/tvheadend-documentation
- Replace all current screenshots with up-to-date, consistent, readable images (suitable for webUI and User Guide)
- Minor renaming of files to improve consistency (e.g. config_misc shoudl be config_general)
Content is now getting better, and we can point people to the online guide as a moving-but-improving target
- Once a week or as needed, re-convert and PR to tvheadend master with new html documents (tweak CSS as/if required)
- Once docs are stable, backport them in tvh master to release/4.0 (html and css) - we could backport the WIP documents but I don't see the real need
- At the same time, branch tvheadend-documentation to release/4.0 and make that the default
This gives us a stable User Guide for 4.0 and matching set of html documents for release
###Open questions:
A. readthedocs.org, github.io or tvheadend.org? RTD supports multiple versions and auto-builds, but has some minor formatting challenges; github is just a dumb standalone web server; tvheadend.org probably means templates/themes and formatting.
readthedocs has the simplicity (push to github, and you're done) which I like and we should try to make it work.
B. wiki versus User Guide? How much should be carried over?
Yaffle view: the wiki should be for more details, linked from the user guide. FAQs and basic how-do-I belong in the User Guide, though.
C. repositories - should we move tvheadend-documentation to the tvheadend github account? That gives better 'consistency' and also makes it less dependent on one anonymous individual
Yaffle view: yes, it shouldn't be connected to an individual (c/f dreamcat's build stuff)
D. repos II - should we move the gihub pages to tvheadend.github.io if we're to use them?
Yaffle view: yes, as above