pinn
pinn copied to clipboard
procount
Project enhancement request: Solicit/create a group of volunteers to help document PINN
Greetings!
Though PINN is an excellent tool, especially relevant to the "non-standard" use-cases for the Raspberry Pi, its major drawback is the (admittedly) abysmal state of the documentation. People who would naturally gravitate to a tool like PINN are driven away by its apparent complexity.
Any serious and powerful tool like PINN needs extensive and carefully crafted documentation, or it becomes a clever technical oddity.
Any user of PINN will understand that your time is already more than spoken-for - you have a laundry list of enhancements and features longer than Santa's Christmas List. Additionally you have the considerable burden of administering your forum topic and providing generous amounts of help to everyone who asks.
As a consequence, documentation suffers. With a real job and the significant burden of this project, it's a wonder that you have any family time, or time for sleep!
Allow me to offer a couple of suggestions:
-
Start a project in parallel with PINN that has the goal of creating a single, detailed, user manual for PINN.
- There is a great deal of documentation already scattered around the various postings and wiki articles that could be incorporated almost without change.. Especially the introductory user instructions.
- Other chapters could be farmed out to volunteers who are either interested in the topic, or have experience and/or expertise in particular subjects - for example, creating custom installation images which I would be glad to help with.
-
Grant authority to certain volunteers to write for, and submit to, your wiki; which wold, in essence, be the same extensive user documentation mentioned above, but in on-line form and administered in essentially the same way. Ultimately, an off-line user manual might be extracted from the wiki text.
- I would suggest the creation of an entirely separate wiki for this documentation.
-
Create an entirely separate "back channel" for those working on the documentation where they can ask questions or share ideas. It might be best to make this "back channel" by invitation only.
What say ye?
Respectfully submitted:
Jim "JR"
Some good ideas there, Jim. So far I haven't had many volunteers for documentation. I doubt many projects do. But I always welcome any pull requests for more documentation. I'm happy to start up a second repo with wiki etc for a user manual if there is enough interest for people to do it. Are you volunteering? 😉
I began with the NOOBS readme which I simply added enhancements to. But once it became too unwieldy, I broke from that with a complete re-write, which I thought was a big improvement. You might like to compare them. I wouldn't say it is abysmal, but I recognise there is still a lot more to do. Sometimes I am too close to the development to recognise what other people need to know. And of course, everyone comes to PINN with their own previous experience and conceptions, so you have to write it several times for the different audiences.
At the end of the day, this is just a hobby for me, because I wanted to improve NOOBS to do what I wanted it to do.
At the end of the day, this is just a hobby for me, because I wanted to improve NOOBS to do what I wanted it to do.
Of course. This is why we, all of us, should be grateful and wish to give back.
I'm happy to start up a second repo with wiki etc for a user manual if there is enough interest for people to do it. Are you volunteering? 😉
Absolutely! Within the obvious constraints of my other projects and commitments.
I wouldn't say it is abysmal, but I recognize there is still a lot more to do.
Well. . . . perhaps "abysmal" is in the eyes of the beholder.
In your case the documentation is reasonably complete because of the large body of knowledge you already have in the subject; as you read, you subconsciously fill in the gaps and blanks.
Those of us, like myself, who do not have the extensive body of knowledge you have cannot do this. All we have is the printed word to go by and if there are gaps, we can't jump across them. So, from the point of view of the uninitiated, the documentation is often woefully inadequate - as our recent "adventure" with custom spins demonstrated.
This is not to say I don't appreciate what you've done. You've accomplished much and I give you total props and respect - but like any form of infrastructure, it's a long complex process and no one man can be expected to do it all.
As an aside, this is why product development and technical writing are two entirely separate divisions with separate marching orders in any reasonably intelligent company. O'Reilly has made a fortune doing "technical writing".
I'm willing to take a crack at it. One place to start is to take the entire body of information, as it exists, and consolidate it into a single, monolithic whole.
And of course, everyone comes to PINN with their own previous experience and conceptions, so you have to write it several times for the different audiences
Not necessarily entirely true. One common organizational technique is to go from the general to the specific, with specific chapters devoted to specific facets of the product that the prospective audiences can read as they need them.
Question: Can you organize a Wiki document into chapters and sections with a table-of-contents? Perhaps an index? A document of this size and complexity would demand careful organization.
What say ye?
I agree with a lot of what you say. I'm happy for you to have a stab at it as it will take a weight off me and allow me to do more development. I can open a private repo for it.
In general, wiki's are designed to have cross-links etc. from which you can create a table of contents. The wiki on github seems a bit primitive. In general I prefer markdown files. Alternatively, I think github has some sort of github-pages which (I think) render markdown pages in github through some sort of css to produce nicely formatted webpages. This seems to be what the RPF/RPT use for their documentation, but I've never had the time to investigate it further. It might be worth a look. Something that auto generates PDF files for offline use would also be good.
My own favorite "development environment" for documentation is Word Perfect and I believe it can create nicely formatted HTML. Scribus is another example though - like Gimp, it's got more aspects than a cat has hair. This itself is an entire line of research - what's the best tool to create GitHub content.
These off-line tools can also create beautiful PDF's, rivaling anything Acrobat can do.
I wouldn't be surprised if RPF et al use something like Dreamweaver, (payware), Scribus, or another completely different FOSS tool.
https://docs.github.com/en/github/working-with-github-pages/getting-started-with-github-pages
Thank you!
This is quite interesting.
One discussion point:
It can be hosted by any active account, but accounts can have only one.
If you don't already have a static web site, you may wish to start it here so that you own it.
You will need to create either an entirely new project for PINN documentation, or create a documentation branch on the existing project.
They also provide suggestions for external content creation.
We need to do additional research to see if more than one person can contribute to the page and/or have control over publishing content, so that you don't have to babysit it. This might cost money.
If you want, I can research the availability of a custom domain like "pinn.com" that, if exist and not too expensive, I will donate.
I'm not really interested in a separate domain or anything that costs. It is possible to host the pages themselves on github. Something like github.io or gh-pages... dunno. I can create a separate repo (private initially maybe) and add you as a collaborator so you can edit content directly.
Update:
Checking availability.
Top level domains like ".com" or (perhaps better), ".help" are $16/year. The "xyz" TLD is.one dollar.
Ok.
If you want, you can "assign" this ticket to me.
You will have to research if you can add collaborators for free, or do you have to pay for an upgrade.
I know that free accounts are rather limited.
I can create a separate repo (private initially maybe) and add you as a collaborator so you can edit content directly.
Repo's are automatically published regardless of its visibility if I understood correctly.
I will research "sandboxing" so we don't make idiots of ourselves.
I have created pinn-doc & pinn-doc.github.io repositories. I had to make it public because the wiki and github pages don't work on private repos.
I don't think this is a good way to publish stuff like this. It appears to be more like a blog site.
https://jharris1993.github.io/github-pages-with-jekyll/
Only the example is a blog.
compare with RPF documentation at https://www.raspberrypi.org/documentation/configuration/
and its source at https://github.com/raspberrypi/documentation/tree/master/configuration
This is becoming more difficult than I thought.
I am running into errors that - according to the documentation - should not be happening. Considerable research has offered several solutions but none worked. Of course, on the Raspberry Pi site, it works like a charm!
So I wrote in the community forum asking for help, and I could not even post it because the offensive word parser kept flagging things.
Viz,: "Parser" contains "arse" - blacklisted British slang. "Documentation" contains "cum" - which is also blacklisted. "Analise" contains "anal" - another blacklisted word. (This includes all tenses and variations)
And my favorite blacklisted word: "Something". Why is "something" blacklisted? It contains the substring "meth"!!
At risk of being blacklisted by GitHub - I think this degree of analysis is a bit anal on their part.
Hmm. I copied my existing README_PINN.md file to the pinn-doc/docs folder, along with an example Table of contents to check it worked. I chose the Architect theme as an example, although I'm not keen on it - I'll have to change it. Just copying the files there made the output available at https://procount.github.io/pinn-doc , although I had to wait a few minutes for all the screenshots to copy across. It didn't seem that difficult.
I think the "minimal" theme is much better.
The reason it's easy for you is that what you're doing is less complex by orders of magnitude. Once I start moving actual documentation with screen captures and code blocks, it gets really interesting!
I need to know why things like this fail, so that I know how to fix them here when they fail as well.
I've run into a snag while asking for help with this:
Their "offensive word" filter is set to level = "anal" - even substrings within normally acceptable words are flagged and prevent me from posting.
For example: "parser", "parse", "parsing" and all other variants fail because they contain the substring "arse" "documntation" (and variants) contain the substring "cum" "something" fails because it contains the substring "meth" And such like.
I would like to report this and ask how I can ask reasonable questions about GitHub pages, without flagging allegedly offensive words. Unfortunately, I cannot find the raspberry pi forum's "meta" page.
Angst regins supreme. I'm going to take a short break, head back to the multi-boot project, and work there until I figure out how to ask questions without them thinking I'm a pedophile or something else vile.
Update:
GitHub has, (at least temporarily) disabled the offensive word filter and I have posted a request for help.
I received the following from GitHub support:
Tammy Metz (GitHub Support)
Feb 1, 2021, 4:01 PM UTC
Hi Jim,
Thanks for reporting this! It definitely does sound like something's not quite right with our filters.
We've cleared these for now and our Community team will be investigating further.
In the meantime, can you try posting again to make sure you're able to get through?
Thanks,
Tammy
GitHub Support
Additional update about creating documentation pages.
I was referred to a site called "Docsify" https://docsify.js.org/#/ and it looks interesting.
More when I know more.