Porting guide modernization #626
Conversation
Create initial directory structure and basic index files for the modernized porting guide. This includes: - Quick start section - Fundamentals section - Modern porting methods - Debugging guides - Vendor-specific information - Legacy porting information - Additional resources
permit building html from the porting-guide-work directory
…xcontrib-mermaid.
…tressing clear pathways for different expertise levels.
…ppeteer configuration.
… the config file path. Simplified the config file JSON structure to only include the args property.
|
Finally got this to build properly, so I guess this is ready for you to proceed with the review, @peat-psuwit ? |
|
@peat-psuwit I have addressed the specific points you mentioned, but the remaining one, i.e. your request that I proof read the whole thing better, is something that I really can't do much about, since my knowledge is the limiting factor here. Also, I cannot see any place I can mark this last requested change as addressed, so I guess that's up to you? I will read through it all, but please understand that beyond things that I have actually tried out myself and properly understood, I don't actually have the necessary knowledge to be able to point out where the text contains factual mistakes. What I can and will do is to attempt addressing this point as well with AI assistance and see if anything turns up. But this carries the risk of "going in circles", as I am sure you understand. However, if you can point out additional relevant source material (code) that I can get the AI to analyze in order to better grasp the inner workings of the Ubuntu Touch system, that could be useful. Lacking something like this, there is no other recourse than for someone who actually has the necessary knowledge to proof read this. |
|
Actually, I have an idea for how to check and adjust the contents. I will close the PR for a bit while I do a some more research and adjustments. I'll reopen it once I have something I think warrants a closer look |
|
Actually it's better to leave the PR open but mark as draft. See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft |
|
Ok. Will fix when I get the chance. |
|
Wow! this is amazing rework ! I can't wait to see it on the web site, as current state of the porting guide is very outdated.. |
…ences between standard and GKI devices.
|
@peat-psuwit : I am reopening this for review now. I will probably not be able to devote as much time to this in the coming couple of weeks. But quick edits should not be a problem. |
|
Also: I removed the mermaid visuals for now, but will rework at least one of them and re-submit them in a separate PR later. |
|
Completed a final check and made 2 minor corrections/additions. Now awaiting review. |
abkro
dismissed
peat-psuwit’s stale review
The remaining comment in the first review addresses an issue that is no longer there, since I completely changed the way the mermaid module is incorporated into the build. Also, I removed the original mermaid visuals, but plan to add them back in a separate PR, once the current PR has been merged.
These comments are very concerning to me. Previously I assumed the AI assistance was used to format, structure and formulate the content, but not to generate new technical details. I assumed that all the technical content itself was human verified. But these quotes above sound to me like there might be specific technical details that have been generated by an AI and have not been human verified. I don't think this can work. AI's are amazingly helpful to find and combine content, but sometimes they get it wrong and hallucinate. The only way to guard against this is to verify. And I think the more niche and obscure the topic the more likely that the AI hallucinates. And now I'm putting this in the context of porting. Porting is hard. Documenting porting might actually be harder! Porting is very niche. It will sometimes go against normal best practices and it will do awkward and unique things which are not done in other contexts. And all that will depend on many intricate details, like which vendors fork from which year, on which hardware, in which android version, ... etc. Even with human porters it is very hard to extrapolate what porter A did and what they claim helped in their situation into something that is useful to other porters. It's often hard to even get a second human to confirm that this is a correct description of a useful step. With "normal" documentation I generally expect that at least two humans agree on any new content before publishing. But with obscure content like porting, I do frequently accept content that has only been validated by that one single person. As long as ... (fill in fuzzy hand waving criteria) ... that person seems trustworthy, responds reasonably when questioned, the content not too outrageous, no obvious and undocumented contradictions. Partially because it's simply unrealistic to find a second contributor who is willing and able to correctly validate the content. So, we trust that one individual and we are careful to give enough context such that the next porter is in a position to take this information and figure out for themselves if and how this helps them. But if we're now going to AI generated content ... I mean to me that feels like playing roulette, I don't see how this can work. I've been sitting on and redrafting this comment now for a few days. I don't want to rain on your parade, but I'm really wondering how we can proceed with this. Maybe we're even both saying the same thing ... "The content must be verified by a human, and that hasn't happened yet". But I think it is unrealistic to expect to be able to find such a human who is able to verify, well ... kind of, everything. It's already not possible in many cases to find someone (other than the author) to even verify a single new small detail and we have to rely on single-opinion-contributions. If the plan is to wait for a reviewer who is able and willing to put their name under all technical details in a large rewrite with substantial new technical content ... I think that's unrealistic. |
|
Thank you for the thoughtful and candid feedback. I greatly appreciate it and the time you spent on it! To put it bluntly, you're right and you're wrong. I use AI extensively in my daytime job at the moment, particularly the LLM Claude.ai which I have been using to rework the porting guide as well. I have used the same strategy in both cases, based on the experience I have gained. In my professional setting: I am using the premium version of Claude.ai, which permits you to define projects. In a project you can define a knowledge base. I proceeded to build this knowledge base in dialogue with the AI, by supplying first what I know to be key articles in the documentation along with the complete article structure of the user documentation. I defined the goals of the project and asked what the AI would need more info about in order to assist me in attaining these goals. This resulted in a more comprehensive knowledge base consisting of a series of other articles in the existing documentation previously authored by myself and my colleagues. After completing this phase, I then requested suggestions for a new structure, based on a set of criteria, and on the projects main goal. The structure I got outlined how the documentation should be divided into main logical areas and also a clear and logical set of articles for each area with contents specified in bullet points. This was already almost spot on. I made minor adjustments. Next, I requested a more detailed specification of the structure and content of each article along with full text for certain sections of certain articles. Again, only minor adjustments necessary. I also requested that the AI produce constructive criticizm of the content produced, referring to the specified criteria and goals. Occasionally, this led to adjustments. Can Claude "hallucinate"?
Claude's strengths: This is getting too long now, so in summary:
I have spent in excess of 20 hours working on this, maybe closer to 30. That in itself is no argument for publishing this, but I have limited time and I am not ready to spend the same amount of time on discussions that are not targeted at specific corrections of issues known to be incorrect. I say this respectfully without any intent of reproach to anyone whatsoever. It is simply a description of my situation and what UBports can expect from me. I also believe that given the current state of things, we would actually be improving the situation for porters by publishing this as is, even if it turned out we would subsequently need to correct some details that were discovered to be erroneous. I believe this would be more beneficial to the community rather than just keeping what we have today. I believe this to the point where I would consider publishing an "unofficial" porting guide to make this available if it does not get accepted in the official documentation (with possible adjustments, if someone other than you and me would be bothered to go through it and check). I am ready and willing to work with someone on adjusting things, though, if this is desired. On a final note: I put your comments to Claude and asked for a response. It is too long to add here, but I can PM you with it if you are interested? |
This PR contains the updated and extended UBports Porting Guide.
The guide has been reworked by Ari Börde Kröyer based on the current guide and the contents of the Halium Generic Build Tools scripts using AI assistance. Although the contents are by and large accurate, it is possible that some details need adjustment. The guide therefore needs to be examined by experienced developers/porters to confirm accuracy.