Archived Doc-Support-Website

[FlorentG74]

Title: PIVX Documentation and Support Dedicated Website
Name: Doc-Support-Website
Term: 4
Cycle Amnt: 1 421
Total Amnt: 5 684
Author: FlorentG74
Receiver: FlorentG74
Address: DMrbxvoa11gLfRq4ortzBa1e41neb5MoP9
Created: 14 Jun 2021
Status: Active

Overview​

PIVX documentation is available in in a variety of medias, including the PIVX forum - mostly for end-users (i.e. step by step tutos) and the Github wiki (more technical info).
It can make the experience of adopting/using PIVX frustrating as:

1. Finding resources is a complicated process and
2. Deprecated resources are left behind and remain online, confusing users.

I wrote an assessment of the current documentation process - available on GitHub: https://github.com/FlorentG74/PIVX-Wiki/blob/master/PIVX-Documentation-Proposal.md
This proposal aims at:

1. Delivering a documentation website that would offer unified documentation to all PIVX users (new users, advanced users, masternode owners)
2. Putting in place a maintenance process making it easy for maintainers/contributors to evolve the documentation at the same time as the software

Objectives​

These are the objectives my proposal aims at meeting:

• Have all user documentation aggregated in one place (technical and non-technical documentation)
• Offer a structure that is easy to navigate for both new and advanced users:
  • An easy to navigate map with a chronological journey for new users
  • A clean structure allowing easy access to any section of the documentation
  • Search capabilities
• Support multiple formats of documentation (Text/Images/Videos)
• Make maintenance easy and accessible to persons with limited technical knowledge; reduce/suppress dependency on Core Developers for maintenance
• Use existing documentation resources as much as possible

Deliverables​

The main deliverables for this proposal will be:

• An integrated knowledge base which will
  • Replace the documentation available on the forum/in the github wiki
  • Be based on GitHub/the md documentation format (re-purposing the existing https://github.com/PIVX-Project/PIVX-Wiki that contains mostly deprecated information)
  • Have a maintenance process that allow for external contributions (via pull requests) while implementing tight controls
• A standalone website (linked to the main PIVX website), serving the content from the knowledge base:
  • A CMS delivering the objectives listed above (Documentation display/navigation/search)
  • A synchronisation with GIT allowing for auto-refresh of the documentation without requiring intervention from a developer. Mechanism for refresh:
    • The website will have a local git repository containing the documents.
    • Addition/Update of documents will be deployed to the website via a 'git pull' from the remote hosted on GitHub (either via a cron or a web hook mechanism)
• A maintenance process for the documentation that will contain the following information:
  • Structure of the documentation website
  • Process to add/update/remove documentation

An update on the progress and on the usage/distribution of the funds will be provided on the forum on a monthly basis.

Approach & Budget/Resources​

Task​	Description​	Person in Charge/Beneficiary​	Estimated Effort​	Distribution​
Website - Initial Framework	Deliver a website based on Grav CMS (a file-based CMD that is based on the Markdown format) Develop a theme for the CMS that integrates with the PIVX color chart	PalmTree​	30 hrs.​	2*250 = 500 PIV​
Website - Enhancements throughout the proposal	Implement enhancements to the basic framework throughout the course of the proposal	FlorentG74/PalmTree depending on requirements​	30 hrs.​	500 PIV​
Knowledge Base - Structure	Define a structure for the knowledge base, and create site map/placeholder pages	FlorentG74​	5 hrs.​	74 PIV​
Knowledge Base - Migration from forum	Migrate all up-to-date articles from the forum to the new pages Flag the deprecated content for suppression	FlorentG74 Open to contributors for 30 PIV/Article​	18 articles / 30 PIV per article​	540 PIV​
Knowledge Base - Review of Youtube videos	Review Youtube videos / flag the deprecated ones for suppression Where available and relevant, integrate the video on corresponding wiki page	FlorentG74 Open to contributors​	20 hrs.​	300 PIV​
Knowledge Base - Troubleshooting section	Review the questions on the Support forum/Discord and incorporate the frequent/relevant ones into the doc articles/troubleshooting sections	FlorentG74​	20 hrs.​	300 PIV​
Knowledge Base - Add Content	Proposal is to organize the documentation in 10 different sections Each section would have a lead contributor receiving a distribution after works has been peer-reviewed The 10 sections would be: Introduction to PIVX/Main Concepts - 150 PIV Getting started - 600 PIV Using the QT Core Wallet - 500 PIV Staking - 400 PIV Using the Command Line Core Wallet - 300 PIV RPC Client - 400 PIV Governance - 200 PIV Masternodes - 200 PIV Best Practices / FAQ - Shared work among all contributors, no explicit distribution Glossary - Shared work among all contributors, no explicit distribution	FlorentG74 Call to contributors​		Up to 2750
Project Management	Coordination of the contributors Coordination of the reviews Coordination with the community for questions/clarifications etc. Definition of the framework for the longer term maintenance of the documentation	FlorentG74​	48 hrs.​	4*180 = 720 PIV​

Total​	Total Amount	Cycle Amount
	5 684 PIV	1 421

Current State​

Some of the work on the website has been started. The basic framework is in place and page templates have been created for the most common types of pages:

Standard page with multiple section/navigation menu:

Search Page:

FAQ Page with collapsible sections:

Tutorial section that makes it easy to have images and description/steps side-by-side:

Assumptions & Risks​

• Hosting/linking to the main website: As per discussions with @palmtree and @Kyeno, hosting and integration on the main website are unlikely to require specific budget lines.
• Some of the deliverables (the content ones) depend heavily on the community. While I will strive to get the whole scope delivered in 4 terms there is a possibility that some topics will not be covered during the lifespan of the proposal. Any budget remaining after the full term will be used to either complete the deliverables listed above, or be used towards some of the stretch objectives if all deliverables have been completed.

Potential Stretch objectives​

The following objectives will be considered if time allows but are not covered by the proposal/budget request (in particular as they have dependencies on Core/Web developers)

• Update the Core Wallet to include a link to the documentation website
• Update the Core Wallet FAQ to point to a wiki page to simplify maintenance
• Have a bot repost the messages from the support section of the forum on Discord to ensure all support requests are seen by the team

Out of scope items​

The following items should be considered as out of the scope of this proposal:

• Developer documentation (contribution/translation/compilation etc)
• New Youtube videos; I don't have the skills / time and believe this should be part of a separate proposal

About myself​

I'm a relatively new member of the PIVX community, and am a strong believer in the value of PIVX.
While researching the coin/setting up my wallet for staking I have experienced first-hand the challenges new PIVX adopters can face in terms of documentation.
I have contributed to the PIVX project as a translator during the month of May (on both the Core Wallet and the website), which gave me visibility on all the content available online to the PIVX community.

Voting:​

Proposal Name: Doc-Support-Website
hash: 4ba2da13725e212b546ab639094621259753016e18daf36b044017d0126a1e58

To vote YES:

mnbudgetvote many 4ba2da13725e212b546ab639094621259753016e18daf36b044017d0126a1e58 yes

To vote NO:

mnbudgetvote many 4ba2da13725e212b546ab639094621259753016e18daf36b044017d0126a1e58 no

To check status:

getbudgetinfo Doc-Support-Website

 

[palmtree]

When looking for support or tutorials, it's often frustrating when you follow documents which lead to dead ends or are incomplete and you have to piece together 2 or 3 parts of different websites to get a solution or resolution. I'm not sure how other coin projects keep their documentation, but I do know that PIVX documentation in recent times is quite fragmented and deprecated. A great example of well managed documentation is the "Arch User Repository" and the "Arch Wiki". For example, search "Arch openvpn" and you will almost always be brought to the most appropriate document or resource. Some attempts have been made by disabling deprecated websites but at the same time disabling the only resource that contained certain other documents. With upcoming features, I think this becomes even more important as additional complications and questions will undoubtedly rise.

 

[Snappy]

Solid proposal, and much needed!

Thank you for taking this on!

 

[FlorentG74]

When looking for support or tutorials, it's often frustrating when you follow documents which lead to dead ends or are incomplete and you have to piece together 2 or 3 parts of different websites to get a solution or resolution. I'm not sure how other coin projects keep their documentation, but I do know that PIVX documentation in recent times is quite fragmented and deprecated. A great example of well managed documentation is the "Arch User Repository" and the "Arch Wiki". For example, search "Arch openvpn" and you will almost always be brought to the most appropriate document or resource. Some attempts have been made by disabling deprecated websites but at the same time disabling the only resource that contained certain other documents. With upcoming features, I think this becomes even more important as additional complications and questions will undoubtedly rise.

Yes @palmtree that's why I put migration of legacy docs as part of it. It's a pain to land on a deprecated doc, almost less frustrating to find nothing and ask support!

 

[FlorentG74]

Solid proposal, and much needed!

Thank you for taking this on!

Thanks @Snappy for the feedback

 

[Eric_Stanek]

Hey @FlorentG74 ! Can you please give a status update on this proposal? I haven't seen any mention anywhere about any activity on this. Thanks.

 

[FlorentG74]

Hi everyone,

As we're approaching the end of the first funding cycle for that project I've put together the below status update for your reference.
Please reach out in case more details are needed or if anything is unclear.

Scope delivered so far:​

• Creation of the base website along with a purple theme and navigation/search menus. Setup of private test server (happy to provide the link to project members interested in reviewing / contributing)
• Creation of the page templates for the various use cases (step-by-step tutorials, FAQs, generic content pages)
• The deployment process documented in the proposal has also been implemented (Manual for now. Automation on the test server coming soon).
• The website is now supported by 2 repositories created in Github:
  • 1 private repo hosting the core website/theme data etc (link can be provided to specific project members upon request)
  • 1 public repo (acting as a submodule to the website) hosting the content as such (currently on https://github.com/FlorentG74/PIVX-Doc-Website-Content)

Next Steps:​

• Shift the focus to content. Create issues on GitHub for community members to take up and work on.
• Start migrating the data from current sources into the website format
• Engage community more actively and enhance the documentation of the contribution workflow.
• Create and animate a discord channel for the potential contributors (as previous discussions on this topic have been lost in translation in the other channels)

Budget Usage:​

Total PIVs disbursed (on the total 1421 received for this cycle): 704, split as follows:

• Website - initial framework: 250 PIV paid to PalmTree
• Website enhancements: 200 PIV paid to FlorentG74
• Knowledge Base - Structure: 74 PIV paid to FlorentG74
• Project Management: 180 PIV paid to FlorentG74

The remaining 717 PIVs will be distributed to individuals contributing content in the coming weeks (content creation constitues the bulk of PIV allocations).

 

[FlorentG74]

Hi everyone, as we approach the end of the 1st cycle for this proposal i just want to share the latest status.

GitHub issues have been created for the various deliverables and we now have 2 sections that are being actively worked on (Qt wallet and staking documentation) and that will complete during the next cycle.

Migration of information from the forum is also in progress (integrated to the relevant core documentation sections or as FAQ items).
I've also started to browse the discord and document the most common issues in the troubleshooting section.

Any questions or comments please let me know!

 

[FlorentG74]

Hi everyone,

Just sharing the link to the GitHub that contains doc content + progress tracker (as open issues)
https://github.com/FlorentG74/PIVX-Doc-Website-Content/issues

Best regards,
Florent

 

[FlorentG74]

Hi everyone,

As we're approaching the end of the second funding cycle for that project I've put together the below status update for your reference.
Please reach out in case more details are needed or if anything is unclear.

Scope delivered so far:​

• Creation of the base website along with a purple theme and navigation/search menus. Setup of private test server available at http://pivx-doc.ydns.eu/pivx_doc/ (updated on a weekly basis at the moment)
• Creation of the page templates for the various use cases (step-by-step tutorials, FAQs, tabbed pages to support multiple OSes, generic content pages)
• The deployment process documented in the proposal has also been implemented (Manual for now. Automation on the test server coming soon).
• The website is now supported by 2 repositories created in Github:
  • 1 private repo hosting the core website/theme data etc (link can be provided to specific project members upon request)
  • 1 public repo (acting as a submodule to the website) hosting the content as such (currently on https://github.com/FlorentG74/PIVX-Doc-Website-Content)
• All the scope has been documented in the form of issues on Github.
• 8 articles from the forum have been migrated/incorporated/rewritten so far. I have also worked on the FAQ and have already incorporated all the recurring questions that are being asked on support. The remainder will be tackled as part of the core wallet section
• Staking and Governance sections have been written
• Core Wallet section is currently being worked on

Next Steps:​

• Continue to produce content.
• Incorporate the feedback from the community into the website (feedback on usability received from 2 community members so far)

Note: Despite being deemed a very useful initiative (and eventually a big time-saver for the individuals contributing to the Discord channels), there hasn't been an overwhelming amount of volunteers stepping up to contribute to the doc writing effort (1 volunteer so far who dropped mid-effort because of personal reasons) so I'll JFDI and plan to distribute PIVs to community members who help in the review process and who provide feedback (either as transfers of PIVs or tips on Discord depending on the effort put).

Budget Usage:​

Total PIVs disbursed (on the total 1421 received for this cycle): 1420, split as follows:

• Website - initial framework: 250 PIV paid to PalmTree
• Website enhancements: 150 PIV paid to FlorentG74
• Project Management: 180 PIV paid to FlorentG74
• Migration of articles from forum: 8*30 = 240 PIV paid to FlorentG74
• Writing of Staking & Governance sections: 600 PIV paid to FlorentG74

The remaining 718 PIVs (Incl. 717 from last cycle) will be distributed to individuals contributing content in the coming weeks (content creation constitues the bulk of PIV allocations).

 

[FlorentG74]

Hi Everyone,

Status:​

This is the final status report on the Doc-Support-Website initiative:

• All deliverables committed in the proposal have been delivered and the website is now in production on: https://docs.pivx.org . There is only 1 minor issue remaining (Youtube videos not loading), root cause and fix are identified and will be deployed by @Kyeno as soon as he's got some availability.
• The framework/code/themes/etc is available on a private GitHub repo to which @Kyeno has access.
• The content itself is available on a public repo (https://github.com/FlorentG74/PIVX-Doc-Website-Content), and contributions can be received either via the opening of issues or via pull requests. The contribution process is documented on the website as well.

What I need from the website/Discord admins:​

• In that GitHub issue, all the forum articles to be taken down are listed. Can a forum admin please take them down? https://github.com/FlorentG74/PIVX-Doc-Website-Content/issues/32
• I'll need help from the core team members to popularize the website when they respond to queries on the #support channel/to raise it to me if they identify missing content
• I'll keep working with Kyeno to integrate the doc website to the core website/replace the links to the deprecated section

Next steps/Way forward:​

• In terms of budget, there have been very limited offers for contributions so I've retained most of the budget on my side. Distributed PIVs:
  • 500 PIV have been paid to PalmTree for putting together the initial website framework
  • 260 PIV have been paid to Yenachar for putting together the section on Masternodes
• I commit to maintaining the website in the longer run (enriching with new scenarios from the #support channel, fixes/enhancements contributed by community members, new sections for new functionalities).
• I will use some of the PIVs I received as part of the initiative to tip community members who submit content to encourage contribution.

Please let me know in case anything is unclear or if you have any questions!

 

[Eric_Stanek]

Excellent update. THANK YOU!