Thank you for sharing your thoughts and insights regarding the decision-making process for our website's documentation. I appreciate your careful consideration of the different aspects involved.
Based on your analysis, it seems that Antora would be an ideal choice for the end user documentation and developer documentation sections of our site. You also mentioned that Antora's long-term maintenance cost for the documentation portions of the site would be relatively low, primarily focusing on keeping the build running and updating the templates. Comparatively, using a tool like Gatsby for versioned/branched documentation might require more effort and custom code to fully accommodate our needs. Therefore, considering the initial development and maintenance perspectives, the benefits of employing Antora for documentation appear to be quite compelling. However, I understand that Antora was not designed for blog-like functionality, as indicated in Antora issue #444 and the intentions of its maintainers. Given this limitation, it would be prudent to explore alternative solutions for our blog, changelogs, and other static content. Antora does not use .yml files as content sources, which poses a challenge for incorporating these specific elements into an Antora-based setup. One option could be to consider using another tool, such as Gatsby, for the blog, changelogs, and static content. Gatsby provides more out-of-the-box support for the versioned documentation use case and offers greater flexibility for customizing and maintaining these aspects of our site. By adopting this approach, we can leverage the strengths of Antora for our documentation while utilizing a tool better suited for handling the blog and static content requirements. In summary, I propose that we use Antora for the entire site, except for the blogs, changelogs, and security advisories and all the content written in .yml format. Antora's intended use case does not align with handling this type of content, but we can explore other solutions like Gatsby to cater to these specific needs. Please let me know your thoughts on this proposed approach, and if you have any alternative suggestions. I value your expertise and look forward to further discussions on this matter. Thank you once again for your comprehensive analysis and contribution to this decision-making process. Best regards, Vandit Singh On Friday, May 19, 2023 at 11:41:31 PM UTC+5:30 m...@basilcrow.com wrote: > On Fri, May 19, 2023 at 10:24 AM 'Gavin Mogan' via Jenkins Developers > <jenkin...@googlegroups.com> wrote: > > Having been around for a number of the GSOC projects, and a number of the > > migration projects. I'm very worried about half finished state that > nobody > > finishes. And honestly spent a lot of time cleaning up content on > jenkins.io > > (some were .html, some were .md, some were .txt) > > So to me, jenkins.io shouldn't be cut over to the new system, until the > new > > system is fully populated. > > I concur with Gavin. I have a strong preference for a more narrow project > scope > that results in a complete migration in production rather than a more wide > project scope that fails to achieve a complete migration in production. The > reason for this strong preference is that for efforts that do not reach > complete > migration in production, the value of the effort approaches zero as time > approaches infinity. A complete migration to production of even one > component > achieves value immediately and is therefore preferable from my perspective. > > > So my suggestion based on me trying to convert jenkins.io to gatsby a > while > > ago and realizing its just too big > > 1) docs.jenkins.io (versioned, antora) > > 2) guides.jenkins.io (versioned, antora, but less likely to update?) > > 3) news.jenkins.io (out of scope of gsoc i think) aka blog. hook up a > headless > > cms like netlifycms (all javascript + github), or maybe even strapi > (really > > nice headless cms, we could have webhooks that update the repo) > > 4) Leave everything else on www.jenkins.io > […] > > It also makes a clear migration plan. We can make docs/tutorials live > when the > > content is fully pulled out. No half measures. > > I concur with Gavin. I have a strong preference for factoring out the docs > content into a new Antora site and atomically cutting over the links from > the > monolithic Awestruct site to the new Antora site, thus achieving complete > migration in production. The same process could be later followed for the > blog. > What remains of the monolithic Awestruct site after the Antora and blog > portions > have been factored out can then be dealt with on a case-by-case basis, but > I > would rather not include this in the scope of GSoC. The reason for this is > that > I fear it would introduce additional risk and delay progress on the Antora > portion of the effort, which is already significant in scope and risk in > and of > itself. > -- You received this message because you are subscribed to the Google Groups "Jenkins Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/990e5268-cf04-40c5-ac4f-364743a4404bn%40googlegroups.com.
