I made a GitBook website to make this asset clear , please contect me
Darwin Build Environment Help Center
I made a GitBook website to make this asset clear , please contect me
Thank you for this initiative. Git books like this one sure look clean and modern.
Spontaneous initiatives are good in general, but before they go too far (and become wasted time) they should be carefully evaluated in their implications. So I have a few questions.
I see you've changed and added a few things compared to the official documentation. Such changes are important to me because they come from user experience, and I'm always interested in improving the documentation. So, apart from reading and comparing the documents (yours and the official doc) all the way down, is there another way (e.g. a diff, or even raw notes) to summarize the changes you made, so that I can include them in the HTML documentation that comes with the product ?
My point in writing the doc in HTML format was that the documentation should always be available, even on machines that are not connected to the world wide web (yes, there are some, often for security reasons). But I admit the appearance of your GitBook is incomparably better than my hand-written HTML document. Can such a GitBook be exported to a single HTML page (embedding its own CSS and JS scripts) while retaining its layout and appearance ?
And last, apart from clearing a few things for yourself (which is always a good thing), what was your broader intent when you decided to write this documentation ? A documentation (such as the one you wrote) is always a time snapshot in the timeline of a product. As the product evolves, the documentation must constantly evolve too. I apologize if what I'm about to say will sound disappointing, but frankly I'm not enthusiastic at the idea of maintaining two separate documentations; and if I were to reference an external one officially, I should be confident that it'll always be up to date. There's nothing so frustrating as a technical document that is wrong because it's outdated.
Yep, I'll send you the changes.
You can export it to PDF if you'd like.
It was really hard for me to read the old version. I knew how much better it could be, so I couldn't stop myself—I ended up spending time (probably unnecessarily) building this website.
Of course, I can give you full control over it. I have no intention of maintaining it myself.
You should just get rid of the old one—it’s not suitable for 2025.
You've done an amazing job creating software that has helped so many people (I hope it will help me soon too!).
But the design… it was killing my eyes. :)
Oh, okay. Well, you did a good job for an online document.
Unfortunately the documentation has to stay local (offline). A PDF is not suitable for comfortable on-screen reading (line lengths don't adjust to window size, and you have less control on hyperlinks).
It would be, of course, technically possible to make the HTML file look more or less like a GitBook, with proper embedded CSS. But the hours I'd spend on it wouldn't solve users' problems other than aesthetic frustration. You do have a point, however, that it looks kinda the 1990s, and that when I have one spare day or two I should change that.
I completely understand your priority for keeping the documentation available offline.
That said, I’d like to gently offer some perspective based on my experience — and likely that of many other users too.
1. This Isn’t Just a Prototype — It’s the Kind of Solution Users Expect Today
What I created isn’t just a demo or side project — it’s aligned with how most high-quality modern tools and open-source projects present their documentation today. Platforms like GitBook, Docusaurus, and others exist for a reason: users need a clear structure, intuitive navigation, and a fast search function. That’s not just about aesthetics — it’s about understanding and efficiency.
When I first opened the current HTML doc, it took me a long time to even figure out what was going on. It’s hard to navigate, not visually structured, and overwhelming. And I’m sure I’m not the only one — most people today are used to polished documentation experiences and will find it hard to work with something that looks and feels outdated.
2. PDF Works Fine for Offline Mode — It’s a Reasonable Trade-off
I get the need for offline availability — but we also need to consider usability. A PDF may not be perfect (e.g., not responsive, sometimes heavier), but people can zoom in, search, and use bookmarks — it’s absolutely fine for occasional offline access. Especially if the alternative is an HTML file with no design, no hierarchy, and no search.
Let’s be honest: in 2025, most users prefer a well-organized, readable online documentation with full features — and will only fall back on offline access as a backup, not their main way of consuming docs.
3. There’s No Need to Maintain Two Versions
I agree completely: having two documentations is unnecessary and confusing. But I’m not proposing that. I’m offering this new one as a direct replacement. You can take full control over it — I’ll even help with exporting it to a standalone HTML file that works fully offline (with all CSS and JS embedded), retaining the same GitBook layout and features.
4. Your Work Deserves Modern Documentation
You’ve built something really valuable, and I truly hope it’ll help me too. But great software deserves documentation that feels current and usable. I say this with full respect: the current version is doing the product a disservice, and I believe this new format is not just a nice-to-have — it’s the expected standard in 2025.
Of course, it’s your project and your decision. I just wanted to share my honest experience, which I believe reflects what many other users would feel.
Let me know if you'd like help moving everything over or setting up the offline export — happy to support however I can.
and happy to get support on the other solve problem topic :)
Sorry for the late response. You said:
“I’ll even help with exporting it to a standalone HTML file that works fully offline (with all CSS and JS embedded), retaining the same GitBook layout and features.”
Well, that's okay then. If you can do that, that would be a great help, and I would definitely replace the old documentation file with this new one. The format is unquestionably better on all aspects, and if it's usable offline, then it'll tick all my checkboxes.
Just wanted to say that I revamped the documentation following your suggestions. It sure looks better now.
https://www.pmbaty.com/darwinbuildenv/documentation/readme.html
It has still room for improvement, e.g. a Javascript-driven interactive decision tree would ideally replace that big "Troubleshooting" section.
Moderators: Pierre-Marie Baty