@James Walters@Martin Wynne
Hi Martin,
Thanks for the GitHub link. I've been following as Rich Bunting (ValleysEnduro).
I hope you are well. This is a long post—about 5-10 minutes to read.
Before diving in, I wanted to check my understanding of your vision. It seems you want to open source Templot5 to reduce time spent explaining things, letting the community help maintain the project while you focus on development and enjoy your hobby. If that’s the case, I think you'll be interested in my proposal to support Templot5 documentation.
As I wrote the proposal, it became quite detailed. I’ve provided a "Too Long; Didn't Read" summary below, but I believe this project can achieve significant improvements.
TL;DR: I propose overhauling Templot5 documentation using the ASD 1000 structure, simplifying the language with STE 100 guidelines, and migrating it to an open-source platform with Sphinx and GitHub Pages. This will improve user accessibility, reduce your workload, and enable community contributions. I also recommend creating a separate GitHub repository for the documentation. A pilot programme will ensure a smooth transition, with outlined risks and mitigations. Notably, Sphinx-generated documentation can resemble the current style, ensuring familiarity. Additionally, I'm happy to host the documentation on a custom subdomain via Github pages, assuming usage remains within a free plan due to the niche nature of the project.
If this sounds good, I’d be happy to start with a pilot section to show how it works in practice. I fully recognise this is your project, so you may want to accept one, all, or a combination of these proposals. I’m eager to hear your thoughts and welcome any ideas.
Combining ASD 1000, STE 100, and Open-Sourcing
Alignment with Your Vision: Templot was designed with a deep understanding of model railway track design, reflecting its origins and phases. My proposal to structure the documentation using ASD 1000 and simplify the language with STE 100 aligns with this by respecting Templot's complexity and flexibility. Organising the documentation into clear sections—Background Information, Procedural Tasks, Reference Material, and User Contributions—will help users navigate Templot’s dual functionality more effectively. This supports both experienced users and those seeking more prescriptive guidance.
Proposed Approach:
- ASD 1000 Structure: I’ll organise the documentation using ASD 1000 methodology, breaking it into clear sections—Background Information, Procedural Tasks, Reference Material, and User Contributions. This will make it easier for users to find the information they need.
- STE 100 (Simplified Technical English): I’ll simplify the language using STE 100 guidelines, ensuring the content is clear, concise, and easily understandable.
- Open-Sourcing with Sphinx and GitHub Pages:I propose migrating the documentation to an open-source platform using Sphinx and GitHub Pages. This offers several benefits:
- Community Contribution: Open-sourcing the documentation encourages community contributions, reducing your burden.
- Version Control and Collaboration: GitHub offers robust version control, making it easy to track changes, revert to previous versions, and collaborate effectively.
- Automated Content Migration: I can use tools to crawl the existing website and migrate the current documentation to Sphinx with minimal disruption.
- Parallel Setup for Smooth Transition: I can run the Sphinx-based documentation alongside the existing system initially, allowing you to see the benefits before a full transition.
- Consistent Look and Feel: Sphinx can closely resemble the current style of Templot5 documentation, minimising disruption during the transition.
Hosting
To make the transition smoother, I'm happy to host the new documentation on a custom subdomain, such as docs.85a.uk, via Github pages or similar platforms. The assumption is that usage will remain within the limits of a free plan, given the niche nature of model railway track design.
Proposal for a Separate Documentation Repository
I recommend setting up a separate GitHub repository dedicated solely to Templot5 documentation. Here’s why this approach would be beneficial:
- Clear Separation of Concerns: Simplified management and dedicated structure for the documentation, independent of the software codebase.
- Improved Collaboration: A dedicated repo will make it easier for the community to contribute, simplifying workflows tailored to the documentation.
- Enhanced Version Control: Independent versioning and focused issue tracking, ensuring the documentation remains a valuable resource.
- Better User Experience: A single, dedicated location for accessing the documentation, with clear communication about updates.
Integration with Current Domain and URL Structure
To maintain consistency with the existing site structure, here’s how the new documentation could be integrated:
- Subdomain Approach: Use a separate subdomain like https://docs.85a.uk/.
- Linking and Navigation: Add links to the new documentation in the main site’s navigation or footer and include links from the forum and existing tech docs. If replacing the existing docs, consider 301 redirects for continuity.
- URL Redirection: Set up 301 redirects from the old tech docs (https://85a.uk/templot/companion/) to the new documentation pages.
Risks and Mitigation
- Community Contribution Challenges:
- Risk: Inconsistent contributions or contributions that don’t align with the desired quality or style.
- Mitigation: Implement clear guidelines and a review process to ensure consistency.
- Disruption During Transition:
- Risk: Temporary confusion for users accustomed to the existing documentation format.
- Mitigation: Communicate the transition plan clearly to users, including a timeline and FAQ section. Consider maintaining both old and new documentation side by side for a short period.
Pilot Programme Details
To ensure a smooth transition and gather valuable feedback, I propose starting with a pilot programme:
- Pilot Scope: Begin with a specific section of the documentation, such as "Creating and Managing Turnouts," to implement the ASD 1000 structure and STE 100 guidelines.
- Timeline: The pilot programme will run for 4 weeks, during which I will collect feedback and make adjustments.
- Feedback Loop: Set up a feedback mechanism, such as a forum thread or a feedback form linked within the pilot documentation.
Conclusion and Vision
This proposal aims to create a more sustainable, user-friendly, and collaborative documentation environment for Templot5. By implementing the ASD 1000 structure, STE 100 language simplifications, and migrating to an open-source platform, I can ensure the documentation remains a valuable resource.
A separate repository will allow the documentation to be managed more effectively, encourage community contributions, and maintain a clear and organised structure. Hosting on a custom subdomain via Vercel will provide a reliable, cost-effective solution. Ultimately, this will free up your time to focus on innovation while the community helps maintain and grow the documentation.
Vision: My vision is for Templot5’s documentation to become a model of clarity and accessibility. With a strong foundation, I can continue to build on it, perhaps even exploring multi-language support or integrating interactive tutorials.
Moving Forward
If this approach sounds good to you, I’d be happy to start with a pilot section of the documentation. I’m confident this strategy will make the documentation more manageable and allow you to get back to what you do best—innovating and pushing Templot5 forward.
Thanks for considering this, Martin. I’m looking forward to hearing your thoughts and working together on this exciting new phase.
About Me
I’m an accredited Engineering Manager with extensive experience in managing and delivering technical documentation for complex platforms. My career includes work on high-profile Category A projects, where I was responsible for ensuring the successful delivery of comprehensive technical documentation. This experience has given me a deep understanding of the importance of clear, structured, and well-maintained documentation.
I’m familiar with the principles of through-life support for technical documentation and have a strong sense of what “good” looks like. My goal is to apply these best practices to the Templot5 documentation, ensuring it is accurate, user-friendly, and sustainable.
Best regards,
Richard
<sup>1</sup>
ASD 1000: Guidelines for standardising technical documentation, used primarily in aerospace and defence industries, aiming to reduce ambiguity and complexity.
<sup>2</sup>
STE 100: A specification for writing clear, concise, and unambiguous text, simplifying language for better accessibility.
Search
TEMPLOT is Martin's hobby project. Everyone is welcome to use it and join in the ongoing developments. Thanks for visiting Templot Club.
Thanks.
's
