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.
…d examples in various sections.
…ng/index.rst before reintroducing this info in the new guide.
…the start of the new porting chapter.
|
|
|
No. That's what the mermaid module is for. It creates a flow chart. |
|
ah. ugh. damn. probably the jenkins setup ... for some reason the jenkins builds always look a bit different 🙈 we really need to fix this 😒 sorry |
|
So. I'm trying to read this, but my first impression to be honest is I get lost all the time. I never know where I end up after I click on a suggested step and end up going back to the start page and trying all over. It seems to me the new organisation is making a lot of accomodations for an "expert" and tries to anticipate what that expert needs, while still writing all the content. And I have the feeling the result is so full of "hey maybe you want to go here or there"-pointers and "this is for experts"-disclaimers that it just becomes hard to read for ... I think for everyone. I'm wondering whether it's worth it to invest so much in this non-linear structure for some "expert" ... I'd say if they are experts then they will have no problem scanning and skipping to get to what they need. And if they are not able to scan and skip because they don't understand the content and the relevance ... well, then they are probably not actually experts, just impatient. |
|
ok. I'm slowly getting somewhere. I start from fundamentals. Always ignore any "maybe you want to" parts. Read top to bottom. At the bottom click "next" I really like the content! it gives much clearer overview of what's the purpose of which part. I love the summaries on the top! with the navigation I still feel a bit challenged |
|
I could probably tone down the "expert/novice" pathways a bit without too much trouble, but I do think it wise to let the different sections start with the main steps in brief, whatever one wishes to call it. "Quick start" or "Steps in brief" or just "In brief" or any better suggestion you might have? But maybe we can try it out this way first while completing what is still missing and then adapt it? Still missing:
|
|
Let me know if there's anything in particular that you're expecting from me. Otherwise, I will just try to address a couple of the points I mentioned above, when I get the chance. I will also check if there is anyone who can help me with the section on finalizing the port. But the things I mention here can be added in an iteration, so they're not really necessary for a first release, in my opinion. The mermaid visuals need to build and display properly, though. |
|
yeah, my feeling is the disclaimers and pointers could be thinned out a bit. I agree to keep the short preambles on top of pages to give a summary. That is super helpful. Wrt missing parts - I would say, ideally we're not removing anything that's already there and is not meant to go away. So, if finalizing is missing in the sense that the existing content hasn't been moved into the new structure, then I'd say that should be fixed before publishing a new version. Any other parts that we don't have today shouldn't block a publication. And in fact going in iterations is often easier than in a big bang. Wrt mermaid, I'm leaning towards kicking that can down the road. I can see them when I build locally, and I expect that they would build correctly once they are merged. I forgot the details, but I think the CI takes some parts from main branch, or from some vanilla uncustomized setup or something. So, I think that is the reason why the CI build of the PR doesn't look right, but I expect this would not affect the actual build of the site once merged. Now, of course it would be great if we could improve our CI build, it actually has a couple of rendering problems (links, etc), but again, that's a separate problem and shouldn't block a merge of this porting modernization. What I think does need to happen is a full review. There should be at least four eyes that agree with the new structure and content. While I'm happy to review it in detail, it will take me some time to finish it, since it is quite big. If someone else wants to step in and do a review I'd certainly welcome it! Maybe just one more thing that I noticed: In the current version the navigation looks like this:
ie a section "Porting" with a couple of chapters The PR looks like this:
ie a section "Porting" with a single chapter called "Ubuntu Touch Porting Guide". The "Ubuntu Touch" seems redundant, but moreover everything is collapsed into a single chapter. I like it better if the hierarchy is that one level flatter and we could pull the content chapters up by one level. But I can't really suggest a useful set of top level chapters because I haven't managed to understand and digest the newly proposed structure |
|
I'm busy on Saturday, but I'll try to follow this up on Sunday. By the way, I agree fully with the need for more eyes on the content mainly, but also the structure. However, my posts in the porting group, and the mention in the last Q&A have not triggered any interest. I wonder, is it because I am the one doing this, and people have seen the many dumb questions I have asked in this group, so they assume the result is just garbage? Or maybe it's down to a general lack of knowledge about AI, so they think this is pure fiction? Or is it simply that they're too busy with other stuff? My point is that if you know how to enlist someone with the necessary knowledge to go through this, please help to make it happen! In the meantime, I will be working on addressing the points you mentioned. |
|
Ah. No. Please don't take it personal! Anyway there is no such thing as a dumb question. From where I sit its just that there is not much contributions to the porting docs, or even the docs overall. And yeah it's probably a mix of lack of knowledge or lack of courage or lack of time. To me you're just one of the few unsung heroes keeping the porting docs up to date. Much appreciated! I wish I could recruit more contributors or reviewers, but it is what it is. Which probably also means that you are stuck with me as a reviewer:) I sense you would wish for someone with more porting know how than me, but well that's also just how it is. And of course it's all volunteer work and people should scratch their itches and otherwise everybody has a life outside so noone to blame, we just make do with what we have 💪 |
|
Ah one other small feedback: I think you can remove the "this is work in progress" disclaimer now. That's understood |
…Reintroduce 'Finalize' information from previous version of guide. Reintroduce and improve 'UpdatePortsFor2004' section.
|
I have now addressed all points you mentioned above. As a result a couple (but not all) of the mermaid visuals are now gone. Don't worry that I'm taking things personally! I'm just seeking to understand and find a way to get help checking the re-written guide. And I greatly appreciate your feedback! The end result will turn out to be a better product thanks to it! I am sure many improvements are still possible, but I am also sincerely convinced that the guide, when the current PR gets published, now vastly surpasses what it previously had to offer. I think that maybe actually publishing this would trigger the feedback that is needed. |
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.