Home of the Squeezebox™ & Transporter® network music players.
Page 1 of 3 123 LastLast
Results 1 to 10 of 22
  1. #1
    Senior Member Greg Erskine's Avatar
    Join Date
    Sep 2006
    Location
    Sydney, Australia
    Posts
    1,917

    piCorePlayer Online Help

    No one likes doing documentation.

    As piCorePlayer is not a commercial product there is really no incentive to do the hard slog and keep the documentation current. I think technical people, given the choice would rather code than document. I certainly would.

    Documentation is important, I know that. I spent 10 years as an Online Technical Writer for a very large Australian organisation, 100,000's of pages. I was mainly support for the Technical writers and instrumental in the publication process.

    So the initial idea was to add "More" links on the pCP GUI. The hope was if we added enough info we wouldn't need any documentation. Well that didn't quite work out, what about release notes, installation how-to's and other less than obvious information. Some of this was already on SourceForge but not integrated into one help system.

    The next idea was the current Online Help. Well that was a step forward but we have to work within some constraints and the result was a system that was a bit cumbersome. The main gripes are it uses pure HTML and the staging server is in the cloud. These issues made doing even minor changes a bit of a chore and proved really awkward when converting user supplied word documents to HTML help. I found HTML easy when you are doing it all the time but after a couple of months break efficiency drops dramatically.

    Documentation gets out of date. As piCorePlayer developed the existing documentation gradually became not applicable or just wrong. The major change came when LMS was introduced as an option. This made statements made about piCorePlayer when it was just a "player" not quite right anymore. Depending when you joined the piCorePlayer train, this was a natural progression or just plain confusing.

    I would like to thank those that have contributed to our existing help. Thanks!

    I would also like to say sorry to those that have offered help over the last few years and probably feel ignored. Each time someone offered help it would push me to look for a better documentation process that would accommodate user input simply. I would do a couple of days research then "try" and find their post again to respond.

    The future. We are investigating other options with these required features:

    1. Documents use markdown.
    2. User input via basic text files.
    3. Source managed by git.
    4. Local staging server.
    5. Automated pushing to production from GitLab.
    6. Potentially, in future, for user input direct via GitLab.
    7. Everything has to be fast.
    8. No day to day management of system or users.

  2. #2
    Senior Member
    Join Date
    Sep 2009
    Location
    Waihi Beach, New Zealand
    Posts
    215
    Quote Originally Posted by Greg Erskine View Post
    No one likes doing documentation.

    As piCorePlayer is not a commercial product there is really no incentive to do the hard slog and keep the documentation current. I think technical people, given the choice would rather code than document. I certainly would.

    Documentation is important, I know that. I spent 10 years as an Online Technical Writer for a very large Australian organisation, 100,000's of pages. I was mainly support for the Technical writers and instrumental in the publication process.

    So the initial idea was to add "More" links on the pCP GUI. The hope was if we added enough info we wouldn't need any documentation. Well that didn't quite work out, what about release notes, installation how-to's and other less than obvious information. Some of this was already on SourceForge but not integrated into one help system.

    The next idea was the current Online Help. Well that was a step forward but we have to work within some constraints and the result was a system that was a bit cumbersome. The main gripes are it uses pure HTML and the staging server is in the cloud. These issues made doing even minor changes a bit of a chore and proved really awkward when converting user supplied word documents to HTML help. I found HTML easy when you are doing it all the time but after a couple of months break efficiency drops dramatically.

    Documentation gets out of date. As piCorePlayer developed the existing documentation gradually became not applicable or just wrong. The major change came when LMS was introduced as an option. This made statements made about piCorePlayer when it was just a "player" not quite right anymore. Depending when you joined the piCorePlayer train, this was a natural progression or just plain confusing.

    I would like to thank those that have contributed to our existing help. Thanks!

    I would also like to say sorry to those that have offered help over the last few years and probably feel ignored. Each time someone offered help it would push me to look for a better documentation process that would accommodate user input simply. I would do a couple of days research then "try" and find their post again to respond.

    The future. We are investigating other options with these required features:

    1. Documents use markdown.
    2. User input via basic text files.
    3. Source managed by git.
    4. Local staging server.
    5. Automated pushing to production from GitLab.
    6. Potentially, in future, for user input direct via GitLab.
    7. Everything has to be fast.
    8. No day to day management of system or users.
    Anything that takes away from coders the chore of user-focused documentation should be a good thing. Best wishes for good results from the steps you've outlined!

    I'm not a coder (well, I was once in the days before Cobol was widespread....) but I would be delighted to assist in any way I can with supporting document production for the pCP community. The whole project is spectacularly good and deserves all the support it can get.
    Digital: Raspberry Pi 3B; piCorePlayer 6 + LMS 8; HifiBerry DAC+DSP > Yamaha RX-V2700 > Jamo speakers
    Analogue: HifiBerry DAC+DSP > Speakercraft MZC-66 > whole house
    Library: External USB drive
    Android: Squeezer app

  3. #3
    Senior Member Greg Erskine's Avatar
    Join Date
    Sep 2006
    Location
    Sydney, Australia
    Posts
    1,917
    Thanks for the kinds words and offer to help.

  4. #4
    Senior Member
    Join Date
    Apr 2007
    Posts
    269
    Quote Originally Posted by Greg Erskine View Post
    No one likes doing documentation.

    The future. We are investigating other options with these required features:

    1. Documents use markdown.
    2. User input via basic text files.
    3. Source managed by git.
    4. Local staging server.
    5. Automated pushing to production from GitLab.
    6. Potentially, in future, for user input direct via GitLab.
    7. Everything has to be fast.
    8. No day to day management of system or users.
    ^^^ This.

    Seems like a fairly standard, run-of-the-mill docs-as-code approach. I applaud this. Given that the structure of the pCP docs is not terribly large or complex, this approach should be easy to implement and, importantly, maintain. By hosting it on GitLab I anticipate interested, docs-minded people can make pull requests and file issues. (Truth be told, I haven't looked to see if the current project allows PRs for docs.)

    I'm looking forward to seeing where this Docs As Code approach leads you. It's the world I live in, although usually working with more semantically-rich languages than just Markdown, although Markdown has played a part in some projects I've done.

  5. #5
    Senior Member Greg Erskine's Avatar
    Join Date
    Sep 2006
    Location
    Sydney, Australia
    Posts
    1,917
    Yeah, most of the documentation/help systems I have been involved with used Microsoft Word or html as source. Most people don't format word consistently enough. Even in a controlled commercial environment where the authors were required to use styles sheet, formatting issues creep in. HTML format is to difficult to control. Markdown seemed about the right common denominator.

    I forgot to mention 2 more requirements:

    9. Output has to be responsive to screen size.
    10. Whole process independent of operating system.

    "easy to implement" is a relative term. Its easy when you look back, but more difficult when you have to discover the path. I didn't know what YAML and TOML was until last week.

    Thanks for your interest.

  6. #6
    Senior Member
    Join Date
    Sep 2009
    Location
    Waihi Beach, New Zealand
    Posts
    215
    Quote Originally Posted by prabbit View Post
    ^^^ This.

    Seems like a fairly standard, run-of-the-mill docs-as-code approach. I applaud this. Given that the structure of the pCP docs is not terribly large or complex, this approach should be easy to implement and, importantly, maintain. By hosting it on GitLab I anticipate interested, docs-minded people can make pull requests and file issues. (Truth be told, I haven't looked to see if the current project allows PRs for docs.)

    I'm looking forward to seeing where this Docs As Code approach leads you. It's the world I live in, although usually working with more semantically-rich languages than just Markdown, although Markdown has played a part in some projects I've done.
    I wonder if my interpretation of "documentation" matches others' expectations? I was thinking of products that could take someone new to the world of RPis, pCP and Linux through all they need to do to end up with a working system, and without getting any further into stuff like the command line than is absolutely essential. So I had no focus at all on code, only on steps to get from the start to enjoying music.

    A while back I knocked up a sample web page on how to set up pCP Bluetooth - https://wbeachdave.weebly.com/bt-on-pcp.html (Because I'd had a bit of a struggle to get Bluetooth working the first time I tried to do it, and thought some more documentation might help.)
    If I get the time, I'll see if I can turn that into a Markdown document.
    Digital: Raspberry Pi 3B; piCorePlayer 6 + LMS 8; HifiBerry DAC+DSP > Yamaha RX-V2700 > Jamo speakers
    Analogue: HifiBerry DAC+DSP > Speakercraft MZC-66 > whole house
    Library: External USB drive
    Android: Squeezer app

  7. #7
    Senior Member Greg Erskine's Avatar
    Join Date
    Sep 2006
    Location
    Sydney, Australia
    Posts
    1,917
    That looks very good.

    I don't know if we'll get to that detail.

    I try to use minimal pictures because they can get out of date quickly. There was a big change going from pCP 5 to pCP 6 and it might all change again.

    I am making sure all pages get dated and noting the version of pCP they were written for. That way people will at least no if the page is current.

    I'm using https://domchristie.github.io/turndown/ to convert from html to markdown.

  8. #8
    Senior Member
    Join Date
    Feb 2011
    Location
    Cheshire, UK
    Posts
    5,001
    Quote Originally Posted by Greg Erskine View Post
    Yeah, most of the documentation/help systems I have been involved with used Microsoft Word or html as source. Most people don't format word consistently enough. Even in a controlled commercial environment where the authors were required to use styles sheet, formatting issues creep in. HTML format is to difficult to control. Markdown seemed about the right common denominator.

    I forgot to mention 2 more requirements:

    9. Output has to be responsive to screen size.
    10. Whole process independent of operating system.

    "easy to implement" is a relative term. Its easy when you look back, but more difficult when you have to discover the path. I didn't know what YAML and TOML was until last week.

    Thanks for your interest.
    When I wrote the Material documentation in Dec 2019 (it really needs updating) I used something called HelpnDoc. You can get a single user licence FOC for use in a non profit basis.
    Itís a Windows WYSISWYG editor that generates (amongst other things) a fully responsive website. There are collaborative versions available but I donít think there is a not for profit collaborative version.
    To see my Material docs, select Information inside Material and scroll to the bottom and follow User Guide.
    VB2.4 storage QNAP TS419p (NFS)
    Living Room - Joggler & SB3 -> Onkyo TS606 -> Celestion F20s
    Office - Pi3+Sreen -> Sony TAFE320 -> Celestion F10s / Pi2+DAC & SB3 -> Onkyo CRN755 -> Wharfedale Modus Cubes
    Dining Room -> SB Boom
    Kitchen -> UE Radio (upgraded to SB Radio)
    Bedroom (Bedside) - Pi2+DAC ->ToppingTP21 ->AKG Headphones
    Bedroom (TV) - SB Touch ->Sherwood AVR ->Mordaunt Short M10s
    Everything controlled by iPeng

  9. #9
    Senior Member Greg Erskine's Avatar
    Join Date
    Sep 2006
    Location
    Sydney, Australia
    Posts
    1,917
    Thanks for the suggestion.

    I saw the Material help a few weeks ago and was impressed. It prompted me to investigate HelpnDoc. Looks good but...

    We have to use tools that are not tied to one OS and the collaboration component was a stumbling block.

    I am hoping using markdown as the document source format will be the key to simple user participation and site management.

    regards
    Greg

  10. #10
    Senior Member
    Join Date
    Feb 2011
    Location
    Cheshire, UK
    Posts
    5,001
    Quote Originally Posted by Greg Erskine View Post
    Thanks for the suggestion.

    I saw the Material help a few weeks ago and was impressed. It prompted me to investigate HelpnDoc. Looks good but...

    We have to use tools that are not tied to one OS and the collaboration component was a stumbling block.

    I am hoping using markdown as the document source format will be the key to simple user participation and site management.

    regards
    Greg
    I do appreciate that. TBH there doesnít seem to be much available out there that will produce decent documentation. I looked for quite a long time for something before I settled on HelpNDoc. What I didnít realise was how quickly Craig would keep adding stuff. Every time I think now would be a good point to update he goes and adds something new!
    Not quite the same with pCP but still a big task. It does need some better documentation IMHO as the same questions are asked over and over again.
    VB2.4 storage QNAP TS419p (NFS)
    Living Room - Joggler & SB3 -> Onkyo TS606 -> Celestion F20s
    Office - Pi3+Sreen -> Sony TAFE320 -> Celestion F10s / Pi2+DAC & SB3 -> Onkyo CRN755 -> Wharfedale Modus Cubes
    Dining Room -> SB Boom
    Kitchen -> UE Radio (upgraded to SB Radio)
    Bedroom (Bedside) - Pi2+DAC ->ToppingTP21 ->AKG Headphones
    Bedroom (TV) - SB Touch ->Sherwood AVR ->Mordaunt Short M10s
    Everything controlled by iPeng

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •