Tasks to be completed
- Determine The Current Status of all Projects/Tools/Libraries
- Examine the current process used for documentation
- Create Standards / Best Practices for Community
- Create Documentation Best Practice badging system.
List of deliverables or work products
- Survey For Maintainers and Community
- Report on Current Documentation processes used.
- Create Recommendations for community
- Create Badging process
- Create templates and guides for achieving badge.
Time to complete
6 months (End 8/28/22)
Leader
Ben W
Initial participant list
Ben W
Bobbi M
John C
Chat Channel
https://discord.com/channels/905194001349627914/943951538345377832
References
TASK FORCE NAME: Documentation Standards
Creation Date
2/28/22
To Do:
Complete survey
Alert Dev newsletter
...
- Besu introduces itself as a product first, whereas Fabric introduces blockchain before a product introduction.
- Should we standardize this? Should we introduce the product or concept?
- Recommendation: Plenty of space in the ReadtheDocs for conceptual resources, let’s introduce the product first. (technical documentation typically assumes the developer knows the fundamentals)
- FAQ style Vs. Concept style. Besu uses FAQ, Fabric conceptual.
- Practical Vs. Theory: Besu very quickly is practical. Fabric documentation puts you through lots of theory before set-up steps.
- Main structure: Fabric is structured much differently from Besu.
- Audience: Even though the Besu documentation is deep and thorough, it is noticeably simpler in structure for a first-time user.
- Social Media: Besu main page is lacking social media links, and Fabric displays them- particularly the Discord is important for community engagement.
Hi team,
I'm a technical writer for ConsenSys protocols and I'd like to raise a discussion about the Besu documentation guidelines.
We recently updated and migrated all the doc guidelines across ConsenSys protocols products to this MkDocs site, which is easily readable and easy for our small team to maintain.
I'm about to update the Besu documentation guidelines for clarity and conciseness, and notice that some of the content should be exactly the same as the ConsenSys doc guide. Since the Besu guidelines already link out to some external guides (Microsoft and Google), should we link out some pages to the ConsenSys guide? The following content from the ConsenSys guide currently applies to the Besu docs:
- Configure and format Markdown
- Markdown extensions
- Documentation style guide
- Documentation release process
The ConsenSys guidelines are open source and anyone can contribute to them. Linking out to this guide would be helpful for our doc team to maintain the content in one location (and there would still be pages in the Besu doc wiki that are unique to Besu, e.g. the contribution workflow).
On the other hand, I understand that Besu is separate from ConsenSys and it may require a complete isolation of content, and the style/markdown guidelines may need to diverge from ConsenSys's in the future. Our team is happy to continue this discussion here and at the next community call.
Thanks,
Alexandra Tran
Comparison of Fabric Vs. SawTooth Documentation
...