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.
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.